caio/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2026-08-28 08:45:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work.

Browse Source
This commit is contained in:
Camilla Berglund
2013-03-29 14:06:23 +01:00
parent 98063d2957
commit e248fb6056
8 changed files with 501 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/Doxyfile.in
View File

@@ -1,4 +1,4 @@
# Doxyfile 1.8.1.2
# Doxyfile 1.8.3.1
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
@@ -126,7 +126,9 @@ FULL_PATH_NAMES = NO
# only done if one of the specified strings matches the left-hand part of
# the path. The tag can be used to show relative paths in the file list.
# If left blank the directory from which doxygen is run is used as the
# path to strip.
# path to strip. Note that you specify absolute paths here, but also
# relative paths, which will be relative from the directory where doxygen is
# started.
STRIP_FROM_PATH =
@@ -229,14 +231,15 @@ OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
# Doxygen selects the parser to use depending on the extension of the files it
# parses. With this tag you can assign which parser to use for a given extension.
# Doxygen has a built-in mapping, but you can override or extend it using this
# tag. The format is ext=language, where ext is a file extension, and language
# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C,
# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make
# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions
# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
# parses. With this tag you can assign which parser to use for a given
# extension. Doxygen has a built-in mapping, but you can override or extend it
# using this tag. The format is ext=language, where ext is a file extension,
# and language is one of the parsers supported by doxygen: IDL, Java,
# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C,
# C++. For instance to make doxygen treat .inc files as Fortran files (default
# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note
# that for custom extensions you also need to set FILE_PATTERNS otherwise the
# files are not read by doxygen.
EXTENSION_MAPPING =
@@ -249,6 +252,13 @@ EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
# When enabled doxygen tries to link words that correspond to documented classes,
# or namespaces to their corresponding documentation. Such a link can be
# prevented in individual cases by by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should
# set this tag to YES in order to let doxygen match functions declarations and
@@ -269,14 +279,14 @@ CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
# For Microsoft's IDL there are propget and propput attributes to indicate getter
# and setter methods for a property. Setting this option to YES (the default)
# will make doxygen replace the get and set methods by a property in the
# documentation. This will only work if the methods are indeed getting or
# For Microsoft's IDL there are propget and propput attributes to indicate
# getter and setter methods for a property. Setting this option to YES (the
# default) will make doxygen replace the get and set methods by a property in
# the documentation. This will only work if the methods are indeed getting or
# setting a simple type. If this is not the case, or you want to show the
# methods anyway, you should set this option to NO.
IDL_PROPERTY_SUPPORT = YES
IDL_PROPERTY_SUPPORT = NO
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
@@ -534,7 +544,8 @@ GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
# documentation sections, marked by \if section-label ... \endif
# and \cond section-label ... \endcond blocks.
ENABLED_SECTIONS =
@@ -592,7 +603,8 @@ LAYOUT_FILE =
# requires the bibtex tool to be installed. See also
# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style
# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
# feature you need bibtex and perl available in the search path.
# feature you need bibtex and perl available in the search path. Do not use
# file names with spaces, bibtex cannot handle them.
CITE_BIB_FILES =
@@ -774,6 +786,13 @@ FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
# If the USE_MD_FILE_AS_MAINPAGE tag refers to the name of a markdown file that
# is part of the input, its contents will be placed on the main page (index.html).
# This can be useful if you have a project on for instance GitHub and want reuse
# the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE =
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
@@ -895,13 +914,23 @@ HTML_FOOTER =
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
# style sheet that is used by each HTML page. It can be used to
# fine-tune the look of the HTML output. If the tag is left blank doxygen
# will generate a default style sheet. Note that doxygen will try to copy
# the style sheet file to the HTML output directory, so don't put your own
# style sheet in the HTML output directory as well, or it will be erased!
# fine-tune the look of the HTML output. If left blank doxygen will
# generate a default style sheet. Note that it is recommended to use
# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this
# tag will in the future become obsolete.
HTML_STYLESHEET =
# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional
# user-defined cascading style sheet that is included after the standard
# style sheets created by doxygen. Using this option one can overrule
# certain style aspects. This is preferred over using HTML_STYLESHEET
# since it does not replace the standard style sheet and is therefor more
# robust against future updates. Doxygen will copy the style sheet file to
# the output directory.
HTML_EXTRA_STYLESHEET =
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
# that these files will be copied to the base HTML output directory. Use the
@@ -986,9 +1015,9 @@ DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify
# the documentation publisher. This should be a reverse domain-name style
# string, e.g. com.mycompany.MyDocSet.documentation.
# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely
# identify the documentation publisher. This should be a reverse domain-name
# style string, e.g. com.mycompany.MyDocSet.documentation.
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
@@ -1173,6 +1202,13 @@ FORMULA_TRANSPARENT = YES
USE_MATHJAX = NO
# When MathJax is enabled you can set the default output format to be used for
# thA MathJax output. Supported types are HTML-CSS, NativeMML (i.e. MathML) and
# SVG. The default value is HTML-CSS, which is slower, but has the best
# compatibility.
MATHJAX_FORMAT = HTML-CSS
# When MathJax is enabled you need to specify the location relative to the
# HTML output directory using the MATHJAX_RELPATH option. The destination
# directory should contain the MathJax.js script. For instance, if the mathjax
@@ -1201,15 +1237,55 @@ MATHJAX_EXTENSIONS =
SEARCHENGINE = YES
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
# implemented using a PHP enabled web server instead of at the web client
# using Javascript. Doxygen will generate the search PHP script and index
# file to put on the web server. The advantage of the server
# based approach is that it scales better to large projects and allows
# full text search. The disadvantages are that it is more difficult to setup
# and does not have live searching capabilities.
# implemented using a web server instead of a web client using Javascript.
# There are two flavours of web server based search depending on the
# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
# searching and an index file used by the script. When EXTERNAL_SEARCH is
# enabled the indexing and searching needs to be provided by external tools.
# See the manual for details.
SERVER_BASED_SEARCH = NO
# When EXTERNAL_SEARCH is enabled doxygen will no longer generate the PHP
# script for searching. Instead the search results are written to an XML file
# which needs to be processed by an external indexer. Doxygen will invoke an
# external search engine pointed to by the SEARCHENGINE_URL option to obtain
# the search results. Doxygen ships with an example indexer (doxyindexer) and
# search engine (doxysearch.cgi) which are based on the open source search engine
# library Xapian. See the manual for configuration details.
EXTERNAL_SEARCH = NO
# The SEARCHENGINE_URL should point to a search engine hosted by a web server
# which will returned the search results when EXTERNAL_SEARCH is enabled.
# Doxygen ships with an example search engine (doxysearch) which is based on
# the open source search engine library Xapian. See the manual for configuration
# details.
SEARCHENGINE_URL =
# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
# search data is written to a file for indexing by an external tool. With the
# SEARCHDATA_FILE tag the name of this file can be specified.
SEARCHDATA_FILE = searchdata.xml
# When SERVER_BASED_SEARCH AND EXTERNAL_SEARCH are both enabled the
# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is
# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple
# projects and redirect the results back to the right project.
EXTERNAL_SEARCH_ID =
# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen
# projects other than the one defined by this configuration file, but that are
# all added to the same external search index. Each project needs to have a
# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id
# of to a relative location where the documentation can be found.
# The format is: EXTRA_SEARCH_MAPPINGS = id1=loc1 id2=loc2 ...
EXTRA_SEARCH_MAPPINGS =
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
@@ -1487,7 +1563,7 @@ EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# pointed to by INCLUDE_PATH will be searched when a #include is found.
SEARCH_INCLUDES = NO
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by
@@ -1785,7 +1861,7 @@ DOT_TRANSPARENT = NO
# makes dot run faster, but since only newer versions of dot (>1.8.10)
# support this, this feature is disabled by default.
DOT_MULTI_TARGETS = YES
DOT_MULTI_TARGETS = NO
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and

40
docs/hints.dox
View File

@@ -1,40 +0,0 @@
/*!
@page hints Window hints
These are all window hints. Some relate to the window itself, others to its
framebuffer or context. They are set to their default values each time the
library is initialized with @ref glfwInit, can be individually set with @ref
glfwWindowHint and reset all at once to their defaults with @ref
glfwDefaultWindowHints.
Note that hints need to be set *before* the creation of the window you wish to
have the specified properties.
| Name | Default values | Supported values |
| ---------------------------- | ------------------------ | ----------------------- |
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` |
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` |
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` |
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_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_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
*/

12
docs/main.dox
View File

@@ -8,9 +8,15 @@ GLFW is a free, Open Source, multi-platform library for opening a window,
creating an OpenGL context and managing input. It is easy to integrate into
existing applications and does not lay claim to the main loop.
[Quick introduction](@ref quick) is a short tutorial for people new to GLFW.
This is the documentation for version 3.0, which has [many new features](@ref news).
[Moving from GLFW 2 to 3](@ref moving) explains what has changed and how to
update existing code to use the GLFW 3 API.
There is a [quick tutorial](@ref quick) for people new to GLFW, which shows how
to write a small but complete program.
If you have used GLFW 2.x in the past, there is a
[transition guide](@ref moving) that explains what has changed and how to update
existing code to use the new API.
As this is still unfinished software, there are still [a number of bugs](@ref bug).
*/

72
docs/moving.dox
View File

@@ -7,7 +7,8 @@
This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include entirely new features unless
they are required when moving an existing code base onto the new API. For example,
use of the new multi-monitor support is required to create fullscreen windows.
use of the new multi-monitor functions are required to create fullscreen windows
with GLFW 3.
@section moving_removed Removed features
@@ -65,11 +66,12 @@ callback, *not* the removal of the character callback itself.
@subsection moving_wheel Mouse wheel position
Scroll events do not represent an absolute state. Instead, it's an
interpretation of a relative change in state, like character input. So, like
character input, there is no sane 'current state' to return. The mouse wheel
callback has been replaced by a [scroll callback](@ref GLFWscrollfun) that
receives two-dimensional scroll offsets.
The `glfwGetMouseWheel` function has been removed. Scroll events do not
represent an absolute state, but is instead an interpretation of a relative
change in state, like character input. So, like character input, there is no
sane 'current state' to return. The mouse wheel callback has been replaced by
a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
offsets.
@subsection moving_stdcall GLFWCALL macro
@@ -87,7 +89,7 @@ point suffixes.
The Win32 port of GLFW 3 will not compile in
[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
Hoever, because the use of the Unicode version of the Win32 API doesn't affect
However, because the use of the Unicode version of the Win32 API doesn't affect
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW uses MBCS mode, there's no need for
@@ -122,13 +124,27 @@ or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in fullscreen mode.
@subsection moving_autopoll Automatic polling of events
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, the event processing functions act on all windows at once.
@subsection moving_terminate Automatic termination
@ref glfwTerminate is no longer registered with `atexit` at initialization. To
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
properly release all resources allocated by GLFW, you should therefore call @ref
glfwTerminate yourself before exiting.
@subsection moving_glu GLU header inclusion
GLFW 3 does not include the GLU header by default and GLU itself has been
deprecated, but you can request that the GLFW 3 header includes it by defining
`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.
@section moving_changed Changes to existing features
@subsection moving_window_handles Window handles
@@ -143,9 +159,10 @@ to an opaque struct.
@subsection moving_monitor Multi-monitor support
GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
type and a set of related functions. To request a fullscreen mode window, you
need to specify which monitor you wish the window to use. There is @ref
glfwGetPrimaryMonitor that provides behaviour similar to that of GLFW 2.
type and a set of related functions. To request a fullscreen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
similar to that of GLFW 2.
@subsection moving_window_close Window closing
@@ -172,34 +189,31 @@ functions.
@subsection moving_keys Physical key input
GLFW 3 uses the physical key locations named after the symbols they generate
using the US keyboard layout, instead of layout-dependent characters like in
GLFW 2. This means that (for example) `GLFW_KEY_BACKSLASH` is always a single
key and is the same key in the same place regardless of what keyboard layouts
the users of your program has.
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
the values generated by the current keyboard layout. The tokens are named
according to the values they would have using the standard US layout, but this
is only a convenience, as most programmers are assumed to know that layout.
This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
is the same key in the same place regardless of what keyboard layouts the users
of your program has.
The key input facility was never meant for text input, although using it that
way worked slightly better in GLFW 2. If you were using it to input text, you
should be using the character callback instead, on both GLFW 2 and 3. This will
give you the characters being input, as opposed to the keys being pressed.
GLFW 3 has key tokens for all keys on a standard keyboard, so instead of having
to remember whether to check for `'a'` or `'A'`, you now check for `GLFW_KEY_A`.
GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
having to remember whether to check for `'a'` or `'A'`, you now check for
`GLFW_KEY_A`.
@subsection moving_video_modes Video mode enumeration
Video mode enumeration is now per-monitor. The `glfwGetDesktopMode` function
has been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor. The @ref glfwGetVideoModes function now returns all available modes
for a monitor instead of requiring you to guess how large an array you need.
@subsection moving_glu GLU header inclusion
Unlike GLFW 2, GLFW 3 doesn't include the GLU header by default, but you can
make it do so by defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW
3 header.
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need. The `glfwGetDesktopMode` function has
been replaced by @ref glfwGetVideoMode, which returns the current mode of
a monitor.
@subsection moving_cursor Cursor positioning

124
docs/news.dox Normal file
View File

@@ -0,0 +1,124 @@
/*!
@page news New features
@tableofcontents
@section news_30 New features in version 3.0
@subsection news_30_cmake CMake build system
GLFW now uses the CMake build system instead of the various makefiles and
project files used by earlier versions. CMake is available for all platforms
supported by GLFW, is present in most package systems and can generate
makefiles and/or project files for most popular development environments.
For more information on how to use CMake, see the
[CMake manual](http://cmake.org/cmake/help/documentation.html).
@subsection new_30_multiwnd Multi-window support
GLFW now supports the creation of multiple windows, each with their own OpenGL
or OpenGL ES context, and all window functions now take a window handle. Event
callbacks are now per-window and are provided with the handle of the window that
received the event. The @ref glfwMakeContextCurrent function has been added to
select which context is current on a given thread.
@subsection news_30_multimon Multi-monitor support
GLFW now explicitly supports multiple monitors. They can be enumerated with
@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
and specified at window creation to make the newly created window fullscren on
that specific monitor.
@subsection news_30_unicode Unicode support
All string arguments to GLFW functions and all strings returned by GLFW use the
UTF-8 encoding. This includes the window title, error string, clipboard text,
monitor and joystick names as well as the extension function arguments (as ASCII
is a subset of UTF-8).
@subsection news_30_clipboard Clipboard text I/O
GLFW now supports reading and writing plain text to and from the system
clipboard, with the @ref glfwGetClipboardString and @ref glfwSetClipboardString
functions.
@subsection news_30_gamma Gamma ramp support
GLFW now supports setting and reading back the gamma ramp of monitors, with the
@ref glfwGetGammaRamp and @ref glfwSetGammaRamp functions. There is also @ref
glfwSetGamma, which generates a ramp from a gamma value and then sets it.
@subsection news_30_gles OpenGL ES and EGL 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 currently only provides an EGL implementation.
GLFW now has an (experimental) EGL context creation backend, which can be
selected through CMake options.
@subsection news_30_error Error callback
GLFW now has an error callback, which can provide your application with much
more detailed diagnostics than was previously possible. The callback is passed
an error code and a description string.
@subsection news_30_wndptr Per-window user pointer
Each window object has a user-defined pointer, retrieved with @ref
glfwGetWindowUserPointer and set with @ref glfwSetWindowUserPointer, to make it
easier to integrate GLFW into C++ code.
@subsection news_30_iconifyfun Window iconification callback
Each window object has a callback for iconification and restoration events, which is
set with @ref glfwSetWindowIconifyCallback.
@subsection news_30_wndposfun Window position callback
Each window object has a callback for position events, which is set with @ref
glfwSetWindowPosCallback.
@subsection news_30_wndpos Window position query
The position of a window can now be retrieved using @ref glfwGetWindowPos.
@subsection news_30_focusfun Window focus callback
Windows now have a callback for focus events, which is set with @ref
glfwSetWindowFocusCallback.
@subsection news_30_wndtitle Initial window title
The title of a window is now specified at creation time, as one of the arguments
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 offscreen rendering in a way compatible with most drivers, as
well as moving a window to a specific position before showing it.
*/

4
docs/quick.dox
View File

@@ -9,6 +9,10 @@ will introduce a few of the most commonly used functions, but there are many
others. To see detailed documentation on any GLFW function, just click on its
name.
This guide assumes no experience with earlier versions of GLFW. If you
have used GLFW 2.x in the past, you should also read the
[transition guide](@ref moving).
@section quick_include Including the GLFW header

160
docs/window.dox Normal file
View File

@@ -0,0 +1,160 @@
/*! @page window Window handling
@tableofcontents
The primary purpose of GLFW is to provide a simple interface to window
management and OpenGL and OpenGL ES context creation. GLFW supports
multiple windows, which can be either a normal desktop window or
a fullscreen window.
@section window_object Window objects
Text here.
@section window_hints Window hints
There are a number of hints that can be set before the creation of a window.
Some affect the window itself, others its framebuffer or context. These hints
are set to their default values each time the library is initialized with @ref
glfwInit, can be individually set with @ref glfwWindowHint and reset all at once
to their defaults with @ref glfwDefaultWindowHints.
Note again that they need to be set *before* the creation of the window you wish
to have the specified properties.
@subsection window_hints_hard Hard and soft constraints
Some window hints are hard constraints. These must match the available
capabilities *exactly* for window and context creation to succeed. Hints
that are not hard constraints are matched as closely as possible, but the
resulting window and context may differ from what these hints requested. To
find out the actual parameters of the created window and context, use the
@ref glfwGetWindowParam function.
The following hints are hard constraints:
- `GLFW_STEREO`
- `GLFW_CLIENT_API`
The following additional hints are hard constraints if requesting an OpenGL
context:
- `GLFW_OPENGL_FORWARD_COMPAT`
- `GLFW_OPENGL_PROFILE`
Hints that do not apply to a given type of window or context are ignored.
@subsection window_hints_fb Framebuffer related hints
The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
depths of the various components of the default framebuffer.
The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
various components of the accumulation buffer.
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
buffers.
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
multisampling.
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
sRGB capable.
@subsection window_hints_ctx Context related hints
The `GLFW_CLIENT_API` hint specifies which client API to create the context
for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.
The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
specify the client API version that the created context must be compatible
with.
For OpenGL, these hints are *not* hard constraints, as they don't have to
match exactly, but @ref glfwCreateWindow will still fail if the resulting
OpenGL version 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.
For OpenGL ES, these hints are hard constraints, as there is no backward
compatibility between OpenGL ES versions.
If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
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 may only be used if the requested OpenGL version is 3.0 or
above. If another client API is requested, this hint is ignored.
If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
specifies whether to create a debug OpenGL context, which may have
additional error and performance issue reporting functionality. If another
client API is requested, this hint is ignored.
If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint 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_NO_PROFILE` to not request a specific profile. If requesting
an OpenGL version below 3.2, `GLFW_OPENGL_NO_PROFILE` must be used. If
another client API is requested, this hint is ignored.
The `GLFW_CONTEXT_ROBUSTNESS` hint 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.
@subsection window_hints_wnd Window related hints
The `GLFW_RESIZABLE` hint specifies whether the window will be resizable by
the user. The window will still be resizable using the @ref
glfwSetWindowSize function. This hint is ignored for fullscreen windows.
The `GLFW_VISIBLE` hint specifies whether the window will be initially
visible. This hint is ignored for fullscreen windows.
@subsection window_hints_values Supported and default values
| Name | Default value | Supported values |
| ---------------------------- | ------------------------ | ----------------------- |
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` |
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` |
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` |
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` |
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` |
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_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_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
| `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
@section window_closing Window closing
Text here.
@section window_dims Window dimensions
Text here.
*/