mirror of
https://github.com/glfw/glfw.git
synced 2024-11-29 07:34:35 +00:00
Documentation work.
This commit is contained in:
Camilla Berglund
parent
7b5b33ee3b
commit
8282a8fbe0
@ -307,7 +307,7 @@ GLFW.
|
||||
`GLFWgammaramp` type for monitor gamma ramp control
|
||||
* Added window parameter to `glfwSwapBuffers`
|
||||
* Changed buffer bit depth parameters of `glfwOpenWindow` to window hints
|
||||
* Changed `glfwOpenWindow` and `glfwSetWindowTitle` to use UTF-8 encoded
|
||||
* Changed `glfwCreateWindow` and `glfwSetWindowTitle` to use UTF-8 encoded
|
||||
strings
|
||||
* Changed `glfwGetProcAddress` to return a (generic) function pointer
|
||||
* Changed `glfwGetVideoModes` to return a dynamic, unlimited number of video
|
||||
@ -367,7 +367,7 @@ GLFW.
|
||||
counterparts
|
||||
* [Cocoa] Bugfix: The `NSOpenGLPFAFullScreen` pixel format attribute caused
|
||||
creation to fail on some machines
|
||||
* [Cocoa] Bugfix: `glfwOpenWindow` did not properly enforce the
|
||||
* [Cocoa] Bugfix: `glfwCreateWindow` did not properly enforce the
|
||||
forward-compatible and context profile hints
|
||||
* [Cocoa] Bugfix: The loop condition for saving video modes used the wrong
|
||||
index variable
|
||||
|
||||
@ -37,8 +37,8 @@ process events. If the running window manager does not support this protocol,
|
||||
the user will not be notified if the application locks up.
|
||||
|
||||
GLFW uses the EWMH `_NET_WM_STATE` protocol to tell the window manager to make
|
||||
the GLFW window fullscreen. If the running window manager does not support this
|
||||
protocol, fullscreen windows may not work properly. GLFW has a fallback code
|
||||
the GLFW window full screen. If the running window manager does not support this
|
||||
protocol, full screen windows may not work properly. GLFW has a fallback code
|
||||
path in case this protocol is unavailable, but every window manager behaves
|
||||
slightly differently in this regard.
|
||||
|
||||
@ -86,7 +86,7 @@ neither is available, no other extensions are used and many GLFW features
|
||||
related to context creation will have no effect or cause errors when used.
|
||||
|
||||
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
|
||||
synchronization (or "vsync"). Where this extension is unavailable, calling @ref
|
||||
synchronization (or 'vsync'). Where this extension is unavailable, calling @ref
|
||||
glfwSwapInterval will have no effect.
|
||||
|
||||
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
|
||||
|
||||
@ -5,10 +5,10 @@
|
||||
@tableofcontents
|
||||
|
||||
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 functions are required to create fullscreen windows
|
||||
with GLFW 3.
|
||||
changed or been removed, but does *not* include
|
||||
[new features](@ref news) unless they are required when moving an existing code
|
||||
base onto the new API. For example, use of the new multi-monitor functions are
|
||||
required to create full screen windows with GLFW 3.
|
||||
|
||||
|
||||
@section moving_removed Removed features
|
||||
@ -31,8 +31,9 @@ TinyCThread.
|
||||
|
||||
However, GLFW 3 has better support for *use from multiple threads* than GLFW
|
||||
2 had. Contexts can be made current on and rendered with from secondary
|
||||
threads, and the documentation explicitly states which functions may or may not
|
||||
be used from secondary threads.
|
||||
threads, and the documentation explicitly states which functions may be used
|
||||
from secondary threads and which may only be used from the main thread, i.e. the
|
||||
thread that calls main.
|
||||
|
||||
|
||||
@subsection moving_image Image and texture loading
|
||||
@ -92,8 +93,8 @@ The Win32 port of GLFW 3 will not compile in
|
||||
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
|
||||
GLFW itself to support it.
|
||||
Therefore, even if an application using GLFW has MBCS mode code, there's no need
|
||||
for GLFW itself to support it.
|
||||
|
||||
|
||||
@subsection moving_windows Support for versions of Windows older than XP
|
||||
@ -121,7 +122,7 @@ version of Windows.
|
||||
The ability to disable and capture system-wide hotkeys like Alt+Tab has been
|
||||
removed. Modern applications, whether they're games, scientific visualisations
|
||||
or something else, are nowadays expected to be good desktop citizens and allow
|
||||
these hotkeys to function even when running in fullscreen mode.
|
||||
these hotkeys to function even when running in full screen mode.
|
||||
|
||||
|
||||
@subsection moving_autopoll Automatic polling of events
|
||||
@ -159,7 +160,7 @@ 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,
|
||||
type and a set of related functions. To request a full screen mode window,
|
||||
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
|
||||
window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
|
||||
similar to that of GLFW 2.
|
||||
@ -211,9 +212,9 @@ having to remember whether to check for `'a'` or `'A'`, you now check for
|
||||
|
||||
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.
|
||||
to guess how large an array you need. The `glfwGetDesktopMode` function, which
|
||||
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
|
||||
returns the current mode of a monitor.
|
||||
|
||||
|
||||
@subsection moving_cursor Cursor positioning
|
||||
|
||||
@ -32,7 +32,7 @@ select which context is current on a given thread.
|
||||
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
|
||||
and specified at window creation to make the newly created window full screen on
|
||||
that specific monitor.
|
||||
|
||||
|
||||
@ -65,9 +65,9 @@ GLFW now supports the creation of OpenGL ES contexts, by setting the
|
||||
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.
|
||||
AMD provides an EGL implementation instead.
|
||||
|
||||
GLFW now has an (experimental) EGL context creation backend, which can be
|
||||
GLFW now has an (experimental) EGL context creation back end, which can be
|
||||
selected through CMake options.
|
||||
|
||||
|
||||
@ -118,7 +118,7 @@ to @ref glfwCreateWindow.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
*/
|
||||
|
||||
@ -110,8 +110,8 @@ glfwSetErrorCallback(error_callback);
|
||||
@section quick_create_window Creating a window and context
|
||||
|
||||
The window (and its context) is created with @ref glfwCreateWindow, which
|
||||
returns a handle to the created window. For example, this creates an 640 by 480
|
||||
pixels windowed mode window:
|
||||
returns a handle to the created window. For example, this creates a 640 by 480
|
||||
windowed mode window:
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
|
||||
@ -131,16 +131,16 @@ if (!window)
|
||||
This handle is then passed to all window related functions, and is provided to
|
||||
you along with input events, so you know which window received the input.
|
||||
|
||||
To create a fullscreen window, you need to specify which monitor the window
|
||||
To create a full screen window, you need to specify which monitor the window
|
||||
should use. In most cases, the user's primary monitor is a good choice. You
|
||||
can get this with @ref glfwGetPrimaryMonitor. To make the above window
|
||||
fullscreen, just pass along the monitor handle:
|
||||
full screen, just pass along the monitor handle:
|
||||
|
||||
@code
|
||||
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
|
||||
@endcode
|
||||
|
||||
Fullscreen windows cover the entire screen, have no border or decorations, and
|
||||
Full screen windows cover the entire screen, have no border or decorations, and
|
||||
change the monitor's resolution to the one most closely matching the requested
|
||||
window size.
|
||||
|
||||
@ -272,8 +272,8 @@ keyboard input, it's possible to create a simple program.
|
||||
|
||||
@snippet simple.c code
|
||||
|
||||
This program creates a 640 by 480 pixels window and runs a loop clearing the
|
||||
screen, rendering a triangle and processing events until the user closes the
|
||||
This program creates a 640 by 480 windowed mode window and runs a loop clearing
|
||||
the screen, rendering a triangle and processing events until the user closes the
|
||||
window. It can be found in the source distribution as `examples/simple.c`, and
|
||||
is by default compiled along with all other examples when you build GLFW.
|
||||
|
||||
|
||||
@ -9,7 +9,11 @@ a fullscreen window.
|
||||
|
||||
@section window_object Window objects
|
||||
|
||||
Text here.
|
||||
The @ref GLFWwindow object encapsulates both a window and a context. They are
|
||||
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
||||
@ref glfwTerminate, if any remain). As the window and context are inseparably
|
||||
linked, the window handle (i.e. window object pointer) is used as a context
|
||||
handle as well, for example when calling @ref glfwMakeContextCurrent.
|
||||
|
||||
|
||||
@section window_hints Window hints
|
||||
@ -79,9 +83,13 @@ 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
|
||||
safe to use the default of version 1.0 for legacy code and you may still
|
||||
get backwards-compatible contexts of version 3.0 and above when available.
|
||||
|
||||
While there is no way to ask the driver for a context of the highest supported
|
||||
version, most drivers provide this when you ask GLFW for a version
|
||||
1.0 context.
|
||||
|
||||
For OpenGL ES, these hints are hard constraints, as there is no backward
|
||||
compatibility between OpenGL ES versions.
|
||||
|
||||
@ -120,7 +128,8 @@ visible. This hint is ignored for fullscreen windows.
|
||||
|
||||
The `GLFW_DECORATED` hint specifies whether the window will have window
|
||||
decorations such as a border, a close widget, etc. This hint is ignored for
|
||||
fullscreen windows.
|
||||
fullscreen windows. Note that even though a window may lack a close widget, it
|
||||
is usually still possible for the user to generate close events.
|
||||
|
||||
|
||||
@subsection window_hints_values Supported and default values
|
||||
@ -155,7 +164,14 @@ fullscreen windows.
|
||||
|
||||
@section window_closing Window closing
|
||||
|
||||
Text here.
|
||||
When the user attempts to close the window, for example by clicking the close
|
||||
widget or using a key chord like Alt+F4, the window's close flag is set and then
|
||||
its close callback is called. The window is not actually destroyed and, unless
|
||||
you are monitoring the close flag, nothing further happens.
|
||||
|
||||
If you do not want the close flag to be set, it can be cleared again from the
|
||||
close callback (or from any other point in your program) with @ref
|
||||
glfwSetWindowShouldClose.
|
||||
|
||||
|
||||
@section window_dims Window dimensions
|
||||
|
||||
@ -60,7 +60,7 @@ extern "C" {
|
||||
* 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.
|
||||
* a full screen window.
|
||||
*/
|
||||
|
||||
|
||||
@ -241,23 +241,23 @@ extern "C" {
|
||||
#define GLFW_REPEAT 2
|
||||
/*! @} */
|
||||
|
||||
/* Keyboard raw key codes.
|
||||
* These key codes are inspired by the USB HID Usage Tables v1.12 (p. 53-60),
|
||||
/*! @defgroup keys Keyboard keys
|
||||
*
|
||||
* These key codes are inspired by the *USB HID Usage Tables v1.12* (p. 53-60),
|
||||
* but re-arranged to map to 7-bit ASCII for printable keys (function keys are
|
||||
* put in the 256+ range).
|
||||
*
|
||||
* The naming of the key codes follow these rules:
|
||||
* - The US keyboard layout is used.
|
||||
* - The US keyboard layout is used
|
||||
* - Names of printable alpha-numeric characters are used (e.g. "A", "R",
|
||||
* "3", etc).
|
||||
* "3", etc.)
|
||||
* - For non-alphanumeric characters, Unicode:ish names are used (e.g.
|
||||
* "COMMA", "LEFT_SQUARE_BRACKET", etc). Note that some names do not
|
||||
* correspond to the Unicode standard (usually for brevity).
|
||||
* - Keys that lack a clear US mapping are named "WORLD_x".
|
||||
* "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not
|
||||
* correspond to the Unicode standard (usually for brevity)
|
||||
* - Keys that lack a clear US mapping are named "WORLD_x"
|
||||
* - For non-printable keys, custom names are used (e.g. "F4",
|
||||
* "BACKSPACE", etc).
|
||||
*/
|
||||
|
||||
/*! @defgroup keys Keyboard keys
|
||||
* "BACKSPACE", etc.)
|
||||
*
|
||||
* @ingroup input
|
||||
* @{
|
||||
*/
|
||||
@ -542,21 +542,34 @@ extern "C" {
|
||||
*************************************************************************/
|
||||
|
||||
/*! @brief Client API function pointer type.
|
||||
*
|
||||
* Generic function pointer used for returning client API function pointers
|
||||
* without forcing a cast from a regular pointer.
|
||||
*
|
||||
* @ingroup context
|
||||
*/
|
||||
typedef void (*GLFWglproc)(void);
|
||||
|
||||
/*! @brief Opaque monitor object.
|
||||
*
|
||||
* Opaque monitor object.
|
||||
*
|
||||
* @ingroup monitor
|
||||
*/
|
||||
typedef struct GLFWmonitor GLFWmonitor;
|
||||
|
||||
/*! @brief Opaque window object.
|
||||
*
|
||||
* Opaque window object.
|
||||
*
|
||||
* @ingroup window
|
||||
*/
|
||||
typedef struct GLFWwindow GLFWwindow;
|
||||
|
||||
/*! @brief The function signature for error callbacks.
|
||||
*
|
||||
* This is the function signature for error callback functions.
|
||||
*
|
||||
* @param[in] error An [error code](@ref errors).
|
||||
* @param[in] description A UTF-8 encoded string describing the error.
|
||||
*
|
||||
@ -567,11 +580,14 @@ typedef struct GLFWwindow GLFWwindow;
|
||||
typedef void (* GLFWerrorfun)(int,const char*);
|
||||
|
||||
/*! @brief The function signature for window position callbacks.
|
||||
*
|
||||
* This is the function signature for window position callback functions.
|
||||
*
|
||||
* @param[in] window The window that the user moved.
|
||||
* @param[in] xpos The new x-coordinate, in pixels, of the upper-left corner of
|
||||
* the client area of the window.
|
||||
* @param[in] ypos The new y-coordinate, in pixels, of the upper-left corner of
|
||||
* the client area of the window.
|
||||
* @param[in] xpos The new x-coordinate, in screen coordinates, of the
|
||||
* upper-left corner of the client area of the window.
|
||||
* @param[in] ypos The new y-coordinate, in screen coordinates, of the
|
||||
* upper-left corner of the client area of the window.
|
||||
*
|
||||
* @sa glfwSetWindowPosCallback
|
||||
*
|
||||
@ -580,9 +596,12 @@ typedef void (* GLFWerrorfun)(int,const char*);
|
||||
typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
|
||||
|
||||
/*! @brief The function signature for window resize callbacks.
|
||||
*
|
||||
* This is the function signature for window size callback functions.
|
||||
*
|
||||
* @param[in] window The window that the user resized.
|
||||
* @param[in] width The new width, in pixels, of the window.
|
||||
* @param[in] height The new height, in pixels, of the window.
|
||||
* @param[in] width The new width, in screen coordinates, of the window.
|
||||
* @param[in] height The new height, in screen coordinates, of the window.
|
||||
*
|
||||
* @sa glfwSetWindowSizeCallback
|
||||
*
|
||||
@ -591,6 +610,9 @@ typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
|
||||
typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
|
||||
|
||||
/*! @brief The function signature for window close callbacks.
|
||||
*
|
||||
* This is the function signature for window close callback functions.
|
||||
*
|
||||
* @param[in] window The window that the user attempted to close.
|
||||
*
|
||||
* @sa glfwSetWindowCloseCallback
|
||||
@ -600,6 +622,9 @@ typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
|
||||
typedef void (* GLFWwindowclosefun)(GLFWwindow*);
|
||||
|
||||
/*! @brief The function signature for window content refresh callbacks.
|
||||
*
|
||||
* This is the function signature for window refresh callback functions.
|
||||
*
|
||||
* @param[in] window The window whose content needs to be refreshed.
|
||||
*
|
||||
* @sa glfwSetWindowRefreshCallback
|
||||
@ -609,6 +634,9 @@ typedef void (* GLFWwindowclosefun)(GLFWwindow*);
|
||||
typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
|
||||
|
||||
/*! @brief The function signature for window focus/defocus callbacks.
|
||||
*
|
||||
* This is the function signature for window focus callback functions.
|
||||
*
|
||||
* @param[in] window The window that was focused or defocused.
|
||||
* @param[in] focused `GL_TRUE` if the window was focused, or `GL_FALSE` if
|
||||
* it was defocused.
|
||||
@ -620,6 +648,10 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
|
||||
typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
|
||||
|
||||
/*! @brief The function signature for window iconify/restore callbacks.
|
||||
*
|
||||
* This is the function signature for window iconify/restore callback
|
||||
* functions.
|
||||
*
|
||||
* @param[in] window The window that was iconified or restored.
|
||||
* @param[in] iconified `GL_TRUE` if the window was iconified, or `GL_FALSE`
|
||||
* if it was restored.
|
||||
@ -631,6 +663,9 @@ typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
|
||||
typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
|
||||
|
||||
/*! @brief The function signature for mouse button callbacks.
|
||||
*
|
||||
* This is the function signature for mouse button callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] button The [mouse button](@ref buttons) that was pressed or
|
||||
* released.
|
||||
@ -643,6 +678,9 @@ typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
|
||||
typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
|
||||
|
||||
/*! @brief The function signature for cursor position callbacks.
|
||||
*
|
||||
* This is the function signature for cursor position callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] xpos The new x-coordinate of the cursor.
|
||||
* @param[in] ypos The new y-coordinate of the cursor.
|
||||
@ -653,7 +691,10 @@ typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int);
|
||||
*/
|
||||
typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
|
||||
|
||||
/*! @brief The function signature for cursor enter/exit callbacks.
|
||||
/*! @brief The function signature for cursor enter/leave callbacks.
|
||||
*
|
||||
* This is the function signature for cursor enter/leave callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] entered `GL_TRUE` if the cursor entered the window's client
|
||||
* area, or `GL_FALSE` if it left it.
|
||||
@ -665,6 +706,9 @@ typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
|
||||
typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
|
||||
|
||||
/*! @brief The function signature for scroll callbacks.
|
||||
*
|
||||
* This is the function signature for scroll callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] xpos The scroll offset along the x-axis.
|
||||
* @param[in] ypos The scroll offset along the y-axis.
|
||||
@ -676,6 +720,9 @@ typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
|
||||
typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
|
||||
|
||||
/*! @brief The function signature for keyboard key callbacks.
|
||||
*
|
||||
* This is the function signature for keyboard key callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] key The [keyboard key](@ref keys) that was pressed or released.
|
||||
* @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT.
|
||||
@ -687,6 +734,9 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
|
||||
typedef void (* GLFWkeyfun)(GLFWwindow*,int,int);
|
||||
|
||||
/*! @brief The function signature for Unicode character callbacks.
|
||||
*
|
||||
* This is the function signature for Unicode character callback functions.
|
||||
*
|
||||
* @param[in] window The window that received the event.
|
||||
* @param[in] character The Unicode code point of the character.
|
||||
*
|
||||
@ -697,6 +747,9 @@ typedef void (* GLFWkeyfun)(GLFWwindow*,int,int);
|
||||
typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
|
||||
|
||||
/*! @brief The function signature for monitor configuration callbacks.
|
||||
*
|
||||
* This is the function signature for monitor configuration callback functions.
|
||||
*
|
||||
* @param[in] monitor The monitor that was connected or disconnected.
|
||||
* @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
|
||||
*
|
||||
@ -706,8 +759,11 @@ typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
|
||||
*/
|
||||
typedef void (* GLFWmonitorfun)(GLFWmonitor*,int);
|
||||
|
||||
/* @brief Video mode type.
|
||||
* @ingroup monitor
|
||||
/*! @brief Video mode type.
|
||||
*
|
||||
* This describes a single video mode.
|
||||
*
|
||||
* @ingroup monitor
|
||||
*/
|
||||
typedef struct
|
||||
{
|
||||
@ -719,6 +775,11 @@ typedef struct
|
||||
} GLFWvidmode;
|
||||
|
||||
/*! @brief Gamma ramp.
|
||||
*
|
||||
* This describes the gamma ramp for a monitor.
|
||||
*
|
||||
* @sa glfwGetGammaRamp glfwSetGammaRamp
|
||||
*
|
||||
* @ingroup gamma
|
||||
*/
|
||||
typedef struct
|
||||
@ -824,7 +885,7 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
|
||||
* - Any additional options or APIs
|
||||
*
|
||||
* For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
|
||||
* backends, the version string may look something like this:
|
||||
* back ends, the version string may look something like this:
|
||||
*
|
||||
* 3.0.0 Win32 WGL MinGW
|
||||
*
|
||||
@ -1066,15 +1127,18 @@ GLFWAPI void glfwWindowHint(int target, int hint);
|
||||
* can use the newly created context, you need to make it current using @ref
|
||||
* glfwMakeContextCurrent.
|
||||
*
|
||||
* Note that the actual properties of the window and context may differ from
|
||||
* what you requested, as not all parameters and hints are hard constraints.
|
||||
* Note that the created window and context may differ from what you requested,
|
||||
* as not all parameters and hints are hard constraints. This includes the
|
||||
* size of the window, especially for full screen windows. To retrieve the
|
||||
* actual properties of the window and context, use queries like @ref
|
||||
* glfwGetWindowParam and @ref glfwGetWindowSize.
|
||||
*
|
||||
* @param[in] width The desired width, in pixels, of the window. This must be
|
||||
* greater than zero.
|
||||
* @param[in] height The desired height, in pixels, of the window. This must
|
||||
* be greater than zero.
|
||||
* @param[in] width The desired width, in screen coordinates, of the window.
|
||||
* This must be greater than zero.
|
||||
* @param[in] height The desired height, in screen coordinates, of the window.
|
||||
* This must be greater than zero.
|
||||
* @param[in] title The initial, UTF-8 encoded window title.
|
||||
* @param[in] monitor The monitor to use for fullscreen mode, or `NULL` to use
|
||||
* @param[in] monitor The monitor to use for full screen mode, or `NULL` to use
|
||||
* windowed mode.
|
||||
* @param[in] share The window whose context to share resources with, or `NULL`
|
||||
* to not share resources.
|
||||
@ -1084,10 +1148,10 @@ GLFWAPI void glfwWindowHint(int target, int hint);
|
||||
* invisible using the `GLFW_VISIBLE` window hint, set its position and then
|
||||
* show it.
|
||||
*
|
||||
* @remarks For fullscreen windows the initial cursor mode is
|
||||
* `GLFW_CURSOR_CAPTURED` and the screensaver is prohibited from starting. For
|
||||
* regular windows the initial cursor mode is `GLFW_CURSOR_NORMAL` and the
|
||||
* screensaver is allowed to start.
|
||||
* @remarks For full screen windows the initial cursor mode is
|
||||
* `GLFW_CURSOR_CAPTURED` and the screen saver is prohibited from starting.
|
||||
* For regular windows the initial cursor mode is `GLFW_CURSOR_NORMAL` and the
|
||||
* screen saver is allowed to start.
|
||||
*
|
||||
* @remarks **Windows:** If the executable has an icon resource named
|
||||
* `GLFW_ICON,` it will be set as the icon for the window. If no such icon is
|
||||
@ -1102,7 +1166,7 @@ GLFWAPI void glfwWindowHint(int target, int hint);
|
||||
*
|
||||
* @note This function may only be called from the main thread.
|
||||
*
|
||||
* @bug **Mac OS X:** The primary monitor is always used for fullscreen
|
||||
* @bug **Mac OS X:** The primary monitor is always used for full screen
|
||||
* windows, regardless of which monitor was specified.
|
||||
*
|
||||
* @sa glfwDestroyWindow
|
||||
@ -1195,6 +1259,8 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
|
||||
* This function sets the position, in screen coordinates, of the upper-left
|
||||
* corner of the client area of the window.
|
||||
*
|
||||
* If it is a full screen window, this function does nothing.
|
||||
*
|
||||
* @param[in] window The window to query.
|
||||
* @param[in] xpos The x-coordinate of the upper-left corner of the client area.
|
||||
* @param[in] ypos The y-coordinate of the upper-left corner of the client area.
|
||||
@ -1224,8 +1290,8 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
|
||||
|
||||
/*! @brief Retrieves the size of the client area of the specified window.
|
||||
*
|
||||
* This function retrieves the size, in pixels, of the client area of the
|
||||
* specified window.
|
||||
* This function retrieves the size, in screen coordinates, of the client area
|
||||
* of the specified window.
|
||||
*
|
||||
* @param[in] window The window whose size to retrieve.
|
||||
* @param[out] width The width of the client area.
|
||||
@ -1239,8 +1305,13 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
|
||||
|
||||
/*! @brief Sets the size of the client area of the specified window.
|
||||
*
|
||||
* This function sets the size, in pixels, of the client area of the specified
|
||||
* window.
|
||||
* This function sets the size, in screen coordinates, of the client area of
|
||||
* the specified window.
|
||||
*
|
||||
* For full screen windows, this function selects and switches to the resolution
|
||||
* closest to the specified size, without affecting the window's context. As
|
||||
* the context is unaffected, the bit depths of the framebuffer remain
|
||||
* unchanged.
|
||||
*
|
||||
* @param[in] window The window to resize.
|
||||
* @param[in] width The desired width of the specified window.
|
||||
@ -1250,10 +1321,6 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
|
||||
*
|
||||
* @note The window manager may put limits on what window sizes are allowed.
|
||||
*
|
||||
* @note For fullscreen windows, this function selects and switches to the
|
||||
* resolution closest to the specified size, without destroying the window's
|
||||
* context.
|
||||
*
|
||||
* @sa glfwGetWindowSize
|
||||
*
|
||||
* @ingroup window
|
||||
@ -1263,7 +1330,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
|
||||
/*! @brief Iconifies the specified window.
|
||||
*
|
||||
* This function iconifies/minimizes the specified window, if it was previously
|
||||
* restored. If it is a fullscreen window, the original monitor resolution is
|
||||
* restored. If it is a full screen window, the original monitor resolution is
|
||||
* restored until the window is restored. If the window is already iconified,
|
||||
* this function does nothing.
|
||||
*
|
||||
@ -1272,7 +1339,7 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
|
||||
* @note This function may only be called from the main thread.
|
||||
*
|
||||
* @bug **Mac OS X:** This function is not yet implemented for
|
||||
* fullscreen windows.
|
||||
* full screen windows.
|
||||
*
|
||||
* @sa glfwRestoreWindow
|
||||
*
|
||||
@ -1283,14 +1350,15 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
|
||||
/*! @brief Restores the specified window.
|
||||
*
|
||||
* This function restores the specified window, if it was previously
|
||||
* iconified/minimized. If the window is already restored, this function does
|
||||
* nothing.
|
||||
* iconified/minimized. If it is a full screen window, the resolution chosen
|
||||
* for the window is restored on the selected monitor. If the window is
|
||||
* already restored, this function does nothing.
|
||||
*
|
||||
* @param[in] window The window to restore.
|
||||
*
|
||||
* @note This function may only be called from the main thread.
|
||||
*
|
||||
* @bug **Mac OS X:** This function is not yet implemented for fullscreen
|
||||
* @bug **Mac OS X:** This function is not yet implemented for full screen
|
||||
* windows.
|
||||
*
|
||||
* @sa glfwIconifyWindow
|
||||
@ -1302,7 +1370,7 @@ GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
|
||||
/*! @brief Makes the specified window visible.
|
||||
*
|
||||
* This function makes the specified window visible, if it was previously
|
||||
* hidden. If the window is already visible or is in fullscreen mode, this
|
||||
* hidden. If the window is already visible or is in full screen mode, this
|
||||
* function does nothing.
|
||||
*
|
||||
* @param[in] window The window to make visible.
|
||||
@ -1318,7 +1386,7 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
|
||||
/*! @brief Hides the specified window.
|
||||
*
|
||||
* This function hides the specified window, if it was previously visible. If
|
||||
* the window is already hidden or is in fullscreen mode, this function does
|
||||
* the window is already hidden or is in full screen mode, this function does
|
||||
* nothing.
|
||||
*
|
||||
* @param[in] window The window to hide.
|
||||
@ -1331,10 +1399,10 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
|
||||
*/
|
||||
GLFWAPI void glfwHideWindow(GLFWwindow* window);
|
||||
|
||||
/*! @brief Returns the monitor that the window uses for fullscreen mode.
|
||||
/*! @brief Returns the monitor that the window uses for full screen mode.
|
||||
*
|
||||
* This function returns the handle of the monitor that the specified window is
|
||||
* in fullscreen on.
|
||||
* in full screen on.
|
||||
*
|
||||
* @param[in] window The window to query.
|
||||
* @return The monitor, or `NULL` if the window is in windowed mode.
|
||||
@ -1440,7 +1508,7 @@ GLFWAPI void glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun
|
||||
*
|
||||
* This function sets the size callback of the specified window, which is
|
||||
* called when the window is resized. The callback is provided with the size,
|
||||
* in pixels, of the client area of the window.
|
||||
* in screen coordinates, of the client area of the window.
|
||||
*
|
||||
* @param[in] window The window whose callback to set.
|
||||
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
|
||||
@ -1479,14 +1547,14 @@ GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun c
|
||||
* called when the client area of the window needs to be redrawn, for example
|
||||
* if the window has been exposed after having been covered by another window.
|
||||
*
|
||||
* On compositing window systems such as Aero, Compiz or Aqua, where the window
|
||||
* contents are saved off-screen, this callback may be called only very
|
||||
* infrequently or never at all.
|
||||
*
|
||||
* @param[in] window The window whose callback to set.
|
||||
* @param[in] cbfun The new callback, or `NULL` to remove the currently set
|
||||
* callback.
|
||||
*
|
||||
* @note On compositing window systems such as Aero, Compiz or Aqua, where the
|
||||
* window contents are saved off-screen, this callback may be called only very
|
||||
* infrequently or never at all.
|
||||
*
|
||||
* @ingroup window
|
||||
*/
|
||||
GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun);
|
||||
@ -1519,7 +1587,7 @@ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyf
|
||||
|
||||
/*! @brief Processes all pending events.
|
||||
*
|
||||
* This function processes only those events that have already been recevied
|
||||
* This function processes only those events that have already been received
|
||||
* and then returns immediately.
|
||||
*
|
||||
* @par New in GLFW 3
|
||||
@ -1527,7 +1595,6 @@ GLFWAPI void glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyf
|
||||
* it or @ref glfwWaitEvents yourself.
|
||||
*
|
||||
* @note This function may only be called from the main thread.
|
||||
* @note This function may not be called from a callback.
|
||||
*
|
||||
* @note This function may not be called from a callback.
|
||||
*
|
||||
@ -1539,11 +1606,10 @@ GLFWAPI void glfwPollEvents(void);
|
||||
|
||||
/*! @brief Waits until events are pending and processes them.
|
||||
*
|
||||
* This function blocks until at least one event has been recevied and then
|
||||
* This function blocks until at least one event has been received and then
|
||||
* processes all received events before returning.
|
||||
*
|
||||
* @note This function may only be called from the main thread.
|
||||
* @note This function may not be called from a callback.
|
||||
*
|
||||
* @note This function may not be called from a callback.
|
||||
*
|
||||
@ -1903,8 +1969,7 @@ GLFWAPI void glfwSetTime(double time);
|
||||
*
|
||||
* This function makes the context of the specified window current on the
|
||||
* calling thread. A context can only be made current on a single thread at
|
||||
* a time and each thread can have only a single current context for a given
|
||||
* client API (such as OpenGL or OpenGL ES).
|
||||
* a time and each thread can have only a single current context at a time.
|
||||
*
|
||||
* @param[in] window The window whose context to make current, or `NULL` to
|
||||
* detach the current context.
|
||||
@ -1957,13 +2022,25 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
|
||||
*
|
||||
* This function sets the swap interval for the current context, i.e. the
|
||||
* number of screen updates to wait before swapping the buffers of a window and
|
||||
* returning from @ref glfwSwapBuffers.
|
||||
* returning from @ref glfwSwapBuffers. This is sometimes called 'vertical
|
||||
* synchronization', 'vertical retrace synchronization' or 'vsync'.
|
||||
*
|
||||
* @param[in] interval The minimum number of screen updates to wait for
|
||||
* until the buffers are swapped by @ref glfwSwapBuffers.
|
||||
*
|
||||
* @remarks This function may be called from secondary threads.
|
||||
*
|
||||
* @remarks Contexts that support either of the `WGL_EXT_swap_control_tear` and
|
||||
* `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals,
|
||||
* which allow the driver to swap even if a frame arrives a little bit late.
|
||||
* You can check for the presence of these extensions using @ref
|
||||
* glfwExtensionSupported. For more information about swap tearing, see the
|
||||
* extension specifications.
|
||||
*
|
||||
* @note Some GPU drivers do not honor the requested swap interval, either
|
||||
* because of user settings that override the request or due to bugs in the
|
||||
* driver.
|
||||
*
|
||||
* @sa glfwSwapBuffers
|
||||
*
|
||||
* @ingroup context
|
||||
@ -1983,7 +2060,7 @@ GLFWAPI void glfwSwapInterval(int interval);
|
||||
*
|
||||
* @note As this functions searches one or more extension strings on each call,
|
||||
* it is recommended that you cache its results if it's going to be used
|
||||
* freqently. The extension strings will not change during the lifetime of
|
||||
* frequently. The extension strings will not change during the lifetime of
|
||||
* a context, so there is no danger in doing this.
|
||||
*
|
||||
* @ingroup context
|
||||
|
||||
Loading…
Reference in New Issue
Block a user