diff --git a/docs/compat.dox b/docs/compat.dox index 69a090e8..3e12e9ae 100644 --- a/docs/compat.dox +++ b/docs/compat.dox @@ -20,21 +20,21 @@ varied window managers in use on Unix-like systems. In order for applications and window managers to work well together, a number of standards and conventions have been developed that regulate behavior outside the scope of the X11 API; most importantly the -Inter-Client Communication Conventions Manual +[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/) (ICCCM) and -Extended Window Manager Hints +[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html) (EWMH) standards. -GLFW uses the ICCCM @c WM_DELETE_WINDOW protocol to intercept the user +GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user attempting to close the GLFW window. If the running window manager does not support this protocol, the close callback will never be called. -GLFW uses the EWMH @c _NET_WM_PING protocol, allowing the window manager notify +GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify the user when the application has stopped responding, i.e. when it has ceased to 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 @c _NET_WM_STATE protocol to tell the window manager to make +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 path in case this protocol is unavailable, but every window manager behaves @@ -45,63 +45,63 @@ slightly differently in this regard. The GLX API is the default API used to create OpenGL contexts on Unix-like systems using the X Window System. -GLFW uses the @c GLXFBConfig API to enumerate and select framebuffer pixel -formats. This requires either GLX 1.3 or greater, or the @c GLX_SGIX_fbconfig +GLFW uses the `GLXFBConfig` API to enumerate and select framebuffer pixel +formats. This requires either GLX 1.3 or greater, or the `GLX_SGIX_fbconfig` extension. Where both are available, the SGIX extension is preferred. If neither is available, GLFW will be unable to create windows. -GLFW uses the @c GLX_MESA_swap_control, @c GLX_EXT_swap_control and @c -GLX_SGI_swap_control extensions to provide vertical retrace synchronization (or -"vsync"), in that order of preference. Where none of these extension are +GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and +`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization +(or "vsync"), in that order of preference. Where none of these extension are available, calling @ref glfwSwapInterval will have no effect. -GLFW uses the @c GLX_ARB_multisample extension to create contexts with -multisampling anti-aliasing. Where this extension is unavailable, the @c -GLFW_SAMPLES hint will have no effect. +GLFW uses the `GLX_ARB_multisample` extension to create contexts with +multisampling anti-aliasing. Where this extension is unavailable, the +`GLFW_SAMPLES` hint will have no effect. -GLFW uses the @c GLX_ARB_create_context extension when available, even when +GLFW uses the `GLX_ARB_create_context` extension when available, even when creating OpenGL contexts of version 2.1 and below. Where this extension is -unavailable, the @c GLFW_CONTEXT_VERSION_MAJOR and @c GLFW_CONTEXT_VERSION_MINOR -hints will only be partially supported, the @c GLFW_OPENGL_DEBUG_CONTEXT hint -will have no effect, and setting the @c GLFW_OPENGL_PROFILE or @c -GLFW_OPENGL_FORWARD_COMPAT hints to a non-zero value will cause @ref +unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` +hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint +will have no effect, and setting the `GLFW_OPENGL_PROFILE` or +`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref glfwCreateWindow to fail. -GLFW uses the @c GLX_ARB_create_context_profile extension to provide support for -context profiles. Where this extension is unavailable, setting the @c -GLFW_OPENGL_PROFILE hint to anything but zero, or setting @c GLFW_CLIENT_API to -anything but @c GLFW_OPENGL_API will cause @ref glfwCreateWindow to fail. +GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for +context profiles. Where this extension is unavailable, setting the +`GLFW_OPENGL_PROFILE` hint to anything but zero, or setting `GLFW_CLIENT_API` to +anything but `GLFW_OPENGL_API` will cause @ref glfwCreateWindow to fail. @section compat_wgl WGL extensions The WGL API is used to create OpenGL contexts on Microsoft Windows and other implementations of the Win32 API, such as Wine. -GLFW uses either the @c WGL_EXT_extension_string or the @c -WGL_ARB_extension_string extension to check for the presence of all other WGL +GLFW uses either the `WGL_EXT_extension_string` or the +`WGL_ARB_extension_string` extension to check for the presence of all other WGL extensions listed below. If both are available, the EXT one is preferred. If 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 @c WGL_EXT_swap_control extension to provide vertical retrace +GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace synchronization (or "vsync"). Where this extension is unavailable, calling @ref glfwSwapInterval will have no effect. -GLFW uses the @c WGL_ARB_pixel_format and @c WGL_ARB_multisample extensions to +GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to create contexts with multisampling anti-aliasing. Where these extensions are -unavailable, the @c GLFW_SAMPLES hint will have no effect. +unavailable, the `GLFW_SAMPLES` hint will have no effect. -GLFW uses the @c WGL_ARB_create_context extension when available, even when +GLFW uses the `WGL_ARB_create_context` extension when available, even when creating OpenGL contexts of version 2.1 and below. Where this extension is -unavailable, the @c GLFW_CONTEXT_VERSION_MAJOR and @c GLFW_CONTEXT_VERSION_MINOR -hints will only be partially supported, the @c GLFW_OPENGL_DEBUG_CONTEXT hint -will have no effect, and setting the @c GLFW_OPENGL_PROFILE or @c -GLFW_OPENGL_FORWARD_COMPAT hints to a non-zero value will cause @ref +unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` +hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint +will have no effect, and setting the `GLFW_OPENGL_PROFILE` or +`GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref glfwCreateWindow to fail. -GLFW uses the @c WGL_ARB_create_context_profile extension to provide support for -context profiles. Where this extension is unavailable, setting the @c -GLFW_OPENGL_PROFILE hint to anything but zero will cause @ref glfwCreateWindow +GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for +context profiles. Where this extension is unavailable, setting the +`GLFW_OPENGL_PROFILE` hint to anything but zero will cause @ref glfwCreateWindow to fail. @section cmopat_osx OpenGL 3.2 on Mac OS X @@ -111,17 +111,17 @@ then only forward-compatible OpenGL 3.2 core profile contexts are supported. There is also still no mechanism for requesting debug contexts. Versions of Mac OS X earlier than 10.7 support at most OpenGL version 2.1. -Because of this, on Mac OS X 10.7, the @c GLFW_CONTEXT_VERSION_MAJOR and -@c GLFW_CONTEXT_VERSION_MINOR hints will fail if given a version above 3.2, the -@c GLFW_OPENGL_FORWARD_COMPAT is required for creating OpenGL 3.2 contexts, the -@c GLFW_OPENGL_DEBUG_CONTEXT hint is ignored and setting the @c -GLFW_OPENGL_PROFILE hint to anything except @c GLFW_OPENGL_CORE_PROFILE will +Because of this, on Mac OS X 10.7, the `GLFW_CONTEXT_VERSION_MAJOR` and +`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 3.2, the +`GLFW_OPENGL_FORWARD_COMPAT` is required for creating OpenGL 3.2 contexts, the +`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored and setting the +`GLFW_OPENGL_PROFILE` hint to anything except `GLFW_OPENGL_CORE_PROFILE` will cause @ref glfwCreateWindow to fail. -Also, on Mac OS X 10.6 and below, the @c GLFW_CONTEXT_VERSION_MAJOR and @c -GLFW_CONTEXT_VERSION_MINOR hints will fail if given a version above 2.1, the @c -GLFW_OPENGL_DEBUG_CONTEXT hint will have no effect, and setting the @c -GLFW_OPENGL_PROFILE or @c GLFW_OPENGL_FORWARD_COMPAT hints to a non-zero value +Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and +`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1, the +`GLFW_OPENGL_DEBUG_CONTEXT` hint will have no effect, and setting the +`GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to a non-zero value will cause @ref glfwCreateWindow to fail. */ diff --git a/docs/main.dox b/docs/main.dox index 49fd118a..44423d16 100644 --- a/docs/main.dox +++ b/docs/main.dox @@ -8,9 +8,9 @@ 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. -@link quick Quick introduction @endlink is a short tutorial for people new to GLFW. +[Quick introduction](@ref quick) is a short tutorial for people new to GLFW. -@link moving Moving from GLFW 2 to 3 @endlink explains what has changed and how -to update existing code to use the GLFW 3 API. +[Moving from GLFW 2 to 3](@ref moving) explains what has changed and how to +update existing code to use the GLFW 3 API. */ diff --git a/docs/moving.dox b/docs/moving.dox index 28987efd..1ab5b90f 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -2,19 +2,19 @@ @page moving Moving from GLFW 2 to 3 -This is a guide for people moving from GLFW 2 to 3. It describes API @em -changes, but does @em not include entirely new features unless they are required -when moving an existing code base onto the new API. One example of this is the -new multi-monitor support, which you are now required to use to create -fullscreen windows. +This is a guide for people moving from GLFW 2 to 3. It describes API *changes*, +but does *not* include entirely new features unless they are required when +moving an existing code base onto the new API. One example of this is the new +multi-monitor support, which you are now required to use to create fullscreen +windows. @section moving_names Library and header names -The GLFW 3 header is named @ref glfw3.h, to avoid collisions with the GLFW 2 @c -glfw.h header, in case they are both installed. Similarly, the GLFW 3 library -is named @c glfw3, except when it's installed as a shared library on -Unix-like systems, where it uses the -soname @c libglfw.so.3 . +The GLFW 3 header is named @ref glfw3.h, to avoid collisions with the GLFW 2 +`glfw.h` header, in case they are both installed. Similarly, the GLFW 3 library +is named `glfw3,` except when it's installed as a shared library on Unix-like +systems, where it uses the [soname](https://en.wikipedia.org/wiki/soname) +`libglfw.so.3`. @section moving_threads Removal of threading functions @@ -31,11 +31,11 @@ The image and texture loading support has been removed. Because GLFW 3 supports multiple windows, window handle parameters have been added to all window-related functions and callbacks. Window handles are of the -@c GLFWwindow* type, i.e. a pointer to an opaque struct. +`GLFWwindow*` type, i.e. a pointer to an opaque struct. @section moving_monitor Multi-monitor support -GLFW 3 provides support for multiple monitors, adding the @c GLFWmonitor* handle +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 something similar to the earlier behaviour. @@ -62,12 +62,12 @@ a window but before calling any OpenGL functions. 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) @c GLFW_KEY_BACKSLASH is always a single +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 has key tokens for all keys, so instead of trying to remember whether to -check for @c 'a' or @c 'A', you now check for @c GLFW_KEY_A. +check for `'a'` or `'A'`, you now check for `GLFW_KEY_A`. 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 @@ -76,7 +76,7 @@ give you the characters being input, as opposed to the keys being pressed. @section moving_video_modes Video mode enumeration -Video mode enumeration is now per-monitor. The @c glfwGetDesktopMode function +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 glfwGetVideoMode function now returns all available modes for a monitor instead of requiring you to guess how large an array you need. @@ -84,7 +84,7 @@ for a monitor instead of requiring you to guess how large an array you need. @section 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 @c GLFW_INCLUDE_GLU before including the GLFW +make it do so by defining `GLFW_INCLUDE_GLU` before including the GLFW 3 header. @section moving_cursor Cursor positioning @@ -97,183 +97,43 @@ function fails silently. @subsection moving_renamed_functions Renamed functions - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
GLFW 2GLFW 3Notes
@c glfwOpenWindow@ref glfwCreateWindowAll channel bit depths are now hints
The defaults are 24-bit color - and depth buffers
Accepts initial window title, optional monitor to go - fullscreen on and optional context to share objects with
@c glfwCloseWindow@ref glfwDestroyWindow
@c glfwOpenWindowHint@ref glfwWindowHintNow also accepts @c GLFW_RED_BITS, @c GLFW_GREEN_BITS, @c - GLFW_BLUE_BITS, @c GLFW_ALPHA_BITS, @c GLFW_DEPTH_BITS and @c - GLFW_STENCIL_BITS
@c glfwEnable@ref glfwSetInputMode
@c glfwDisable@ref glfwSetInputMode
@c glfwGetMousePos@ref glfwGetCursorPos
@c glfwSetMousePos@ref glfwSetCursorPos
@c glfwSetMousePosCallback@ref glfwSetCursorPosCallback
@c glfwSetMouseWheelCallback@ref glfwSetScrollCallbackAccepts two-dimensional scroll offsets as doubles
@c glfwGetJoystickPos@ref glfwGetJoystickAxes
@c glfwGetGLVersion@ref glfwGetWindowParamUse @c GLFW_OPENGL_VERSION_MAJOR, @c GLFW_OPENGL_VERSION_MINOR and @c - GLFW_OPENGL_REVISION
@c glfwGetDesktopMode@ref glfwGetVideoModeReturns the current mode of a monitor
+| GLFW 2 | GLFW 3 | Notes | +| --------------------------- | ----------------------------- | ----- | +| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints
Accepts initial window title, optional monitor to go fullscreen on and optional context to share objects with | +| `glfwCloseWindow` | @ref glfwDestroyWindow | | +| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens | +| `glfwEnable` | @ref glfwSetInputMode | | +| `glfwDisable` | @ref glfwSetInputMode | | +| `glfwGetMousePos` | @ref glfwGetCursorPos | | +| `glfwSetMousePos` | @ref glfwSetCursorPos | | +| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | | +| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles | +| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | | +| `glfwGetGLVersion` | @ref glfwGetWindowParam | Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` | +| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor | @subsection moving_renamed_tokens Renamed tokens - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
GLFW 2GLFW 3Notes
@c GLFW_OPENGL_VERSION_MAJOR@c GLFW_CONTEXT_VERSION_MAJORRenamed as it applies to OpenGL ES as well
@c GLFW_OPENGL_VERSION_MINOR@c GLFW_CONTEXT_VERSION_MINORRenamed as it applies to OpenGL ES as well
@c GLFW_FSAA_SAMPLES@c GLFW_SAMPLESRenamed to match the OpenGL API
@c GLFW_ACTIVE@c GLFW_FOCUSEDRenamed to match the window focus callback
@c GLFW_WINDOW_NO_RESIZE@c GLFW_RESIZABLEThe default has been inverted
@c GLFW_MOUSE_CURSOR@c GLFW_CURSOR_MODEUsed with @c glfwSetInputMode
Accepts @c GLFW_CURSOR_NORMAL, @c - GLFW_CURSOR_HIDDEN and @c GLFW_CURSOR_CAPTURED
@c GLFW_KEY_ESC@c GLFW_KEY_ESCAPE
@c GLFW_KEY_DEL@c GLFW_KEY_DELETE
@c GLFW_KEY_PAGEUP@c GLFW_KEY_PAGE_UP
@c GLFW_KEY_PAGEDOWN@c GLFW_KEY_PAGE_DOWN
@c GLFW_KEY_KP_NUM_LOCK@c GLFW_KEY_NUM_LOCK
@c GLFW_KEY_LCTRL@c GLFW_KEY_LEFT_CONTROL
@c GLFW_KEY_LSHIFT@c GLFW_KEY_LEFT_SHIFT
@c GLFW_KEY_LALT@c GLFW_KEY_LEFT_ALT
@c GLFW_KEY_LSUPER@c GLFW_KEY_LEFT_SUPER
@c GLFW_KEY_RCTRL@c GLFW_KEY_RIGHT_CONTROL
@c GLFW_KEY_RSHIFT@c GLFW_KEY_RIGHT_SHIFT
@c GLFW_KEY_RALT@c GLFW_KEY_RIGHT_ALT
@c GLFW_KEY_RSUPER@c GLFW_KEY_RIGHT_SUPER
+| GLFW 2 | GLFW 3 | Notes | +| --------------------------- | ---------------------------- | ----- | +| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well | +| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well | +| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API | +| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback | +| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted | +| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR_MODE` | Used with @ref glfwSetInputMode | +| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | | +| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | | +| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | | +| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | | +| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | | +| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | | +| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | | +| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | | +| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | | +| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | | +| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | | +| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | | +| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | | */ diff --git a/docs/quick.dox b/docs/quick.dox index fc9f104b..72de88f2 100644 --- a/docs/quick.dox +++ b/docs/quick.dox @@ -23,25 +23,25 @@ This defines all the constants, types and function prototypes of the GLFW API. It also includes the OpenGL header, and defines all the constants and types necessary for it to work on your platform. -For example, under Windows you are normally required to include @c windows.h -before including @c GL/gl.h. This would make your source file tied to Windows +For example, under Windows you are normally required to include `windows.h` +before including `GL/gl.h`. This would make your source file tied to Windows and pollute your code's namespace with the whole Win32 API. -Instead, the GLFW header takes care of this for you, not by including @c -windows.h, but rather by itself duplicating only the necessary parts of it. It -does this only where needed, so if @c windows.h @em is included, the GLFW header +Instead, the GLFW header takes care of this for you, not by including +`windows.h`, but rather by itself duplicating only the necessary parts of it. +It does this only where needed, so if `windows.h` *is* included, the GLFW header does not try to redefine those symbols. In other words: -@arg Do @em not include the OpenGL headers yourself, as GLFW does this for you -@arg Do @em not include @c windows.h or other platform-specific headers unless - you plan on using those APIs directly -@arg If you @em do need to include such headers, do it @em before including the - GLFW and it will detect this +* Do *not* include the OpenGL headers yourself, as GLFW does this for you Do +* *not* include `windows.h` or other platform-specific headers unless + you plan on using those APIs directly +* If you *do* need to include such headers, do it *before* including the + GLFW and it will detect this -Starting with version 3.0, the GLU header @c glu.h is no longer included by -default. If you wish to include it, define @c GLFW_INCLUDE_GLU before the +Starting with version 3.0, the GLU header `glu.h` is no longer included by +default. If you wish to include it, define `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header. @code @@ -84,7 +84,7 @@ In case @ref glfwInit or any other GLFW function fails, an error is reported to the GLFW error callback. You can receive these reports by setting the error callback. The callback function itself should match the signature of @ref GLFWerrorfun. Here is a simple error callback that just prints the error -description to @c stderr. +description to `stderr`. @code void error_callback(int error, const char* description) @@ -113,7 +113,7 @@ pixels windowed mode window: GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); @endcode -If window creation fails, @c NULL will be returned, so you need to check whether +If window creation fails, `NULL` will be returned, so you need to check whether it did. @code @@ -170,9 +170,9 @@ be checked with @ref glfwWindowShouldClose. When the user attempts to close the window, either by pressing the close widget in the title bar or using a key combination like Alt+F4, this flag is set to 1. -Note that the window isn't actually closed, so you are expected to -monitor this flag and either destroy the window or give some kind of feedback to -the user. +Note that **the window isn't actually closed**, so you are expected to monitor +this flag and either destroy the window or give some kind of feedback to the +user. @code while (!glfwWindowShouldClose(window)) @@ -194,10 +194,10 @@ for example pressing the escape key. Once you have a current OpenGL context, you can use OpenGL normally. In this tutorial, a multi-colored rotating triangle will be rendered. The window size, -needed here by @c glViewport and @c glOrtho, is retrieved using @ref +needed here by `glViewport` and `glOrtho`, is retrieved using @ref glfwGetWindowSize. However, if you only need it for updating the viewport when the window size changes, you can set a window size callback using @ref -glfwSetWindowSizeCallback and call @c glViewport from there. +glfwSetWindowSizeCallback and call `glViewport` from there. @code void window_size_callback(GLFWwindow* window, int width, int height) @@ -211,7 +211,7 @@ void window_size_callback(GLFWwindow* window, int width, int height) For the triangle to rotate properly, a time source is needed. GLFW provides @ref glfwGetTime, which returns the number of seconds since @ref glfwInit as -a @c double. The time source used is the most accurate on each platform and +a `double`. The time source used is the most accurate on each platform and generally has micro- or nanosecond resolution. @code diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index 65a13311..a55dbc69 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -559,7 +559,7 @@ typedef struct GLFWmonitor GLFWmonitor; typedef struct GLFWwindow GLFWwindow; /*! @brief The function signature for error callbacks. - * @param[in] error An @link errors error code @endlink. + * @param[in] error An [error code](@ref errors). * @param[in] description A UTF-8 encoded string describing the error. * @ingroup error * @@ -607,7 +607,7 @@ typedef void (* GLFWwindowrefreshfun)(GLFWwindow*); /*! @brief The function signature for window focus/defocus callbacks. * @param[in] window The window that was focused or defocused. - * @param[in] focused @c GL_TRUE if the window was focused, or @c GL_FALSE if + * @param[in] focused `GL_TRUE` if the window was focused, or `GL_FALSE` if * it was defocused. * @ingroup window * @@ -617,7 +617,7 @@ typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int); /*! @brief The function signature for window iconify/restore callbacks. * @param[in] window The window that was iconified or restored. - * @param[in] iconified @c GL_TRUE if the window was iconified, or @c GL_FALSE + * @param[in] iconified `GL_TRUE` if the window was iconified, or `GL_FALSE` * if it was restored. * @ingroup window * @@ -627,9 +627,9 @@ typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int); /*! @brief The function signature for mouse button callbacks. * @param[in] window The window that received the event. - * @param[in] button The @link buttons mouse button @endlink that was pressed - * or released. - * @param[in] action One of @c GLFW_PRESS or @c GLFW_RELEASE. + * @param[in] button The [mouse button](@ref buttons) that was pressed or + * released. + * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. * @ingroup input * * @sa glfwSetMouseButtonCallback @@ -648,8 +648,8 @@ typedef void (* GLFWcursorposfun)(GLFWwindow*,int,int); /*! @brief The function signature for cursor enter/exit callbacks. * @param[in] window The window that received the event. - * @param[in] entered @c GL_TRUE if the cursor entered the window's client - * area, or @c GL_FALSE if it left it. + * @param[in] entered `GL_TRUE` if the cursor entered the window's client + * area, or `GL_FALSE` if it left it. * @ingroup input * * @sa glfwSetCursorEnterCallback @@ -668,8 +668,7 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double); /*! @brief The function signature for keyboard key callbacks. * @param[in] window The window that received the event. - * @param[in] key The @link keys keyboard key @endlink that was pressed or - * released. + * @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. * @ingroup input * @@ -688,7 +687,7 @@ typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int); /*! @brief The function signature for monitor configuration callbacks. * @param[in] monitor The monitor that was connected or disconnected. - * @param[in] event One of @c GLFW_CONNECTED or @c GLFW_DISCONNECTED. + * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. * @ingroup monitor * * @sa glfwSetMonitorCallback @@ -728,7 +727,7 @@ typedef struct * a program terminates GLFW should be terminated in order to free allocated * resources, memory, etc. * - * @return @c GL_TRUE if successful, or @c GL_FALSE if an error occurred. + * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. * @ingroup init * * @remarks Additional calls to this function after successful initialization @@ -739,8 +738,8 @@ typedef struct * @note This function may take several seconds to complete on some systems, * while on other systems it may take only a fraction of a second to complete. * - * @note Mac OS X: This function will change the current directory of the - * application to the @c Contents/Resources subdirectory of the application's + * @note **Mac OS X:** This function will change the current directory of the + * application to the `Contents/Resources` subdirectory of the application's * bundle, if present. * * @sa glfwTerminate @@ -766,9 +765,9 @@ GLFWAPI int glfwInit(void); GLFWAPI void glfwTerminate(void); /*! @brief Retrieves the version of the GLFW library. - * @param[out] major Where to store the major version number, or @c NULL. - * @param[out] minor Where to store the minor version number, or @c NULL. - * @param[out] rev Where to store the revision number, or @c NULL. + * @param[out] major Where to store the major version number, or `NULL`. + * @param[out] minor Where to store the minor version number, or `NULL`. + * @param[out] rev Where to store the revision number, or `NULL`. * @ingroup init * * @remarks This function may be called before @ref glfwInit. @@ -798,7 +797,7 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); GLFWAPI const char* glfwGetVersionString(void); /*! @brief Sets the error callback. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup error * @@ -817,7 +816,7 @@ GLFWAPI void glfwSetErrorCallback(GLFWerrorfun cbfun); /*! @brief Returns the currently connected monitors. * @param[out] count The size of the returned array. - * @return An array of monitor handles, or @c NULL if an error occurred. + * @return An array of monitor handles, or `NULL` if an error occurred. * @ingroup monitor * * @sa glfwGetPrimaryMonitor @@ -825,7 +824,7 @@ GLFWAPI void glfwSetErrorCallback(GLFWerrorfun cbfun); GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); /*! @brief Returns the primary monitor. - * @return The primary monitor, or @c NULL if an error occurred. + * @return The primary monitor, or `NULL` if an error occurred. * @ingroup monitor * * @sa glfwGetMonitors @@ -850,14 +849,14 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* h /*! @brief Returns the name of the specified monitor. * @param[in] monitor The monitor to query. - * @return The UTF-8 encoded name of the monitor, or @c NULL if an error + * @return The UTF-8 encoded name of the monitor, or `NULL` if an error * occurred. * @ingroup monitor */ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); /*! @brief Sets the monitor configuration callback. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup monitor */ @@ -866,7 +865,7 @@ GLFWAPI void glfwSetMonitorCallback(GLFWmonitorfun cbfun); /*! @brief Returns the available video modes for the specified monitor. * @param[in] monitor The monitor to query. * @param[out] count The number of video modes in the returned array. - * @return An array of video modes, or @c NULL if an error occurred. + * @return An array of video modes, or `NULL` if an error occurred. * @ingroup monitor * * @sa glfwGetVideoMode @@ -913,21 +912,21 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); /*! @brief Resets all window hints to their default values * - * The @c GLFW_RED_BITS, @c GLFW_GREEN_BITS, @c GLFW_BLUE_BITS, @c - * GLFW_ALPHA_BITS and @c GLFW_STENCIL_BITS hints are set to 8. + * The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS` + * and `GLFW_STENCIL_BITS` hints are set to 8. * - * The @c GLFW_DEPTH_BITS hint is set to 24. + * The `GLFW_DEPTH_BITS` hint is set to 24. * - * The @c GLFW_VISIBLE and @c GLFW_RESIZABLE hints are set to 1. + * The `GLFW_VISIBLE` and `GLFW_RESIZABLE` hints are set to 1. * - * The @c GLFW_CLIENT_API hint is set to @c GLFW_OPENGL_API. + * The `GLFW_CLIENT_API` hint is set to `GLFW_OPENGL_API`. * - * The @c GLFW_CONTEXT_VERSION_MAJOR and @c GLFW_CONTEXT_VERSION_MINOR - * hints are set to 1 and 0, respectively. + * The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints are + * set to 1 and 0, respectively. * - * The @c GLFW_CONTEXT_ROBUSTNESS hint is set to @c GLFW_NO_ROBUSTNESS. + * The `GLFW_CONTEXT_ROBUSTNESS` hint is set to `GLFW_NO_ROBUSTNESS`. * - * The @c GLFW_OPENGL_PROFILE hint is set to @c GLFW_OPENGL_NO_PROFILE. + * The `GLFW_OPENGL_PROFILE` hint is set to `GLFW_OPENGL_NO_PROFILE`. * * All other hints are set to 0. * @@ -952,54 +951,54 @@ GLFWAPI void glfwDefaultWindowHints(void); * @par Hard and soft constraints * * Some window hints are hard constraints. These must match the available - * capabilities @em exactly for window and context creation to succeed. Hints + * 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: - * @arg @c GLFW_STEREO - * @arg @c GLFW_CLIENT_API + * * `GLFW_STEREO` + * * `GLFW_CLIENT_API` * * The following additional hints are hard constraints if requesting an OpenGL * context: - * @arg @c GLFW_OPENGL_FORWARD_COMPAT - * @arg @c GLFW_OPENGL_PROFILE + * * `GLFW_OPENGL_FORWARD_COMPAT` + * * `GLFW_OPENGL_PROFILE` * * Hints that do not apply to a given type of window or context are ignored. * * @par Framebuffer hints * - * The @c GLFW_RED_BITS, @c GLFW_GREEN_BITS, @c GLFW_BLUE_BITS, @c - * GLFW_ALPHA_BITS, @c GLFW_DEPTH_BITS and @c GLFW_STENCIL_BITS hints specify - * the desired bit depths of the various components of the default framebuffer. + * 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 @c GLFW_ACCUM_RED_BITS, @c GLFW_ACCUM_GREEN_BITS, @c - * GLFW_ACCUM_BLUE_BITS and @c GLFW_ACCUM_ALPHA_BITS hints specify the desired - * bit depths of the various components of the accumulation buffer. + * 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 @c GLFW_AUX_BUFFERS hint specifies the desired number of auxiliary + * The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary * buffers. * - * The @c GLFW_STEREO hint specifies whether to use stereoscopic rendering. + * The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. * - * The @c GLFW_SAMPLES hint specifies the desired number of samples to use - * for multisampling. + * The `GLFW_SAMPLES` hint specifies the desired number of samples to use for + * multisampling. * - * The @c GLFW_SRGB_CAPABLE hint specifies whether the framebuffer should be + * The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be * sRGB capable. * * @par Context hints * - * The @c GLFW_CLIENT_API hint specifies which client API to create the context - * for. Possible values are @c GLFW_OPENGL_API and @c GLFW_OPENGL_ES_API. + * 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 @c GLFW_CONTEXT_VERSION_MAJOR and @c GLFW_CONTEXT_VERSION_MINOR hints + * 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 @em not hard constraints, as they don't have to + * 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 @@ -1008,36 +1007,36 @@ GLFWAPI void glfwDefaultWindowHints(void); * 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 @c GLFW_OPENGL_FORWARD_COMPAT hint + * 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 @c GLFW_OPENGL_DEBUG_CONTEXT hint + * 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 @c GLFW_OPENGL_PROFILE hint - * specifies which OpenGL profile to create the context for. Possible values - * are one of @c GLFW_OPENGL_CORE_PROFILE or @c GLFW_OPENGL_COMPAT_PROFILE, - * or @c GLFW_OPENGL_NO_PROFILE to not request a specific profile. If - * requesting an OpenGL version below 3.2, @c GLFW_OPENGL_NO_PROFILE must be - * used. 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 @c GLFW_CONTEXT_ROBUSTNESS hint specifies the robustness strategy to - * be used by the context. This can be one of @c GLFW_NO_RESET_NOTIFICATION - * or @c GLFW_LOSE_CONTEXT_ON_RESET, or @c GLFW_NO_ROBUSTNESS to not - * request a robustness strategy. + * 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. * * @par Window hints * - * The @c GLFW_RESIZABLE hint specifies whether the window will be resizable - * by the user. The window will still be resizable using the @ref + * 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 @c GLFW_VISIBLE hint specifies whether the window will be initially + * The `GLFW_VISIBLE` hint specifies whether the window will be initially * visible. This hint is ignored for fullscreen windows. * * @note This function may only be called from the main thread. @@ -1053,11 +1052,11 @@ GLFWAPI void glfwWindowHint(int target, int hint); * @param[in] height The desired height, in pixels, 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 @c NULL to use + * @param[in] monitor The monitor to use for fullscreen mode, or `NULL` to use * windowed mode. - * @param[in] share The window whose context to share resources with, or @c - * NULL to not share resources. - * @return The handle of the created window, or @c NULL if an error occurred. + * @param[in] share The window whose context to share resources with, or `NULL` + * to not share resources. + * @return The handle of the created window, or `NULL` if an error occurred. * @ingroup window * * @remarks Most of the options for how the window and its context should be @@ -1068,27 +1067,27 @@ GLFWAPI void glfwWindowHint(int target, int hint); * glfwMakeContextCurrent. * * @remarks To create the window at a specific position, make it initially - * invisible using the @c GLFW_VISIBLE window hint, set its position and then + * invisible using the `GLFW_VISIBLE` window hint, set its position and then * show it. * - * @remarks For fullscreen windows the initial cursor mode is @c - * GLFW_CURSOR_CAPTURED and the screensaver is prohibited from starting. For - * regular windows the initial cursor mode is @c GLFW_CURSOR_NORMAL and the + * @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 In order to determine the actual parameters of an opened window, * use @ref glfwGetWindowParam and @ref glfwGetWindowSize. * - * @remarks Windows: If the executable has an icon resource named @c - * GLFW_ICON, it will be set as the icon for the window. If no such icon is - * present, the @c IDI_WINLOGO icon will be used instead. + * @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 + * present, the `IDI_WINLOGO` icon will be used instead. * - * @remarks Mac OS X: 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. Also, the first time a window is opened the menu bar is - * populated with common commands like Hide, Quit and About. The (minimal) - * about dialog uses information from the application's bundle. For more - * information on bundles, see the Bundle Programming Guide provided by Apple. + * @remarks **Mac OS X:** 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. + * Also, the first time a window is opened the menu bar is populated with + * common commands like Hide, Quit and About. The (minimal) about dialog uses + * information from the application's bundle. For more information on bundles, + * see the Bundle Programming Guide provided by Apple. * * @note This function may only be called from the main thread. * @@ -1146,7 +1145,7 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); * @param[out] ypos The y-coordinate of the upper-left corner of the client area. * @ingroup window * - * @remarks Either or both coordinate parameters may be @c NULL. + * @remarks Either or both coordinate parameters may be `NULL`. * * @sa glfwSetWindowPos */ @@ -1162,7 +1161,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * the client area of the window. * * @remarks If you wish to set an initial window position you should create - * a hidden window (using @ref glfwWindowHint and @c GLFW_VISIBLE), set its + * a hidden window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its * position and then show it. * * @note It is very rarely a good idea to move an already visible window, as it @@ -1172,11 +1171,11 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * * @note The window manager may put limits on what positions are allowed. * - * @bug X11: Some window managers ignore the set position of hidden - * (i.e. unmapped) windows, instead placing them where it thinks is - * appropriate once they are shown. + * @bug **X11:** Some window managers ignore the set position of hidden (i.e. + * unmapped) windows, instead placing them where it thinks is appropriate once + * they are shown. * - * @bug Mac OS X: The screen coordinate system is inverted. + * @bug **Mac OS X:** The screen coordinate system is inverted. * * @sa glfwGetWindowPos */ @@ -1218,7 +1217,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 + * @bug **Mac OS X:** This function is not yet implemented for * fullscreen windows. * * @sa glfwRestoreWindow @@ -1233,7 +1232,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window); * * @note This function may only be called from the main thread. * - * @bug Mac OS X: This function is not yet implemented for + * @bug **Mac OS X:** This function is not yet implemented for * fullscreen windows. * * @sa glfwIconifyWindow @@ -1268,7 +1267,7 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window); /*! @brief Returns the monitor that the window uses for fullscreen mode * @param[in] window The window to query. - * @return The monitor, or @c NULL if the window is in windowed mode. + * @return The monitor, or `NULL` if the window is in windowed mode. * @ingroup window */ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); @@ -1281,40 +1280,39 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * * @par Window parameters * - * The @c GLFW_FOCUSED parameter indicates whether the window is focused. + * The `GLFW_FOCUSED` parameter indicates whether the window is focused. * - * The @c GLFW_ICONIFIED parameter indicates whether the window is iconified. + * The `GLFW_ICONIFIED` parameter indicates whether the window is iconified. * - * The @c GLFW_VISIBLE parameter indicates whether the window is visible. + * The `GLFW_VISIBLE` parameter indicates whether the window is visible. * - * The @c GLFW_RESIZABLE parameter indicates whether the window is resizable + * The `GLFW_RESIZABLE` parameter indicates whether the window is resizable * by the user. * * @par Context parameters * - * The @c GLFW_CLIENT_API parameter indicates the client API provided by the - * window's context; either @c GLFW_OPENGL_API or @c GLFW_OPENGL_ES_API. + * The `GLFW_CLIENT_API` parameter indicates the client API provided by the + * window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. * - * The @c GLFW_CONTEXT_VERSION_MAJOR, @c GLFW_CONTEXT_VERSION_MINOR and @c - * GLFW_CONTEXT_REVISION parameters indicate the client API version of the + * The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and + * `GLFW_CONTEXT_REVISION` parameters indicate the client API version of the * window's context. * - * The @c GLFW_OPENGL_FORWARD_COMPAT parameter is @c GL_TRUE if the window's - * context is an OpenGL forward-compatible one, or @c GL_FALSE otherwise. + * The `GLFW_OPENGL_FORWARD_COMPAT` parameter is `GL_TRUE` if the window's + * context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise. * - * The @c GLFW_OPENGL_DEBUG_CONTEXT parameter is @c GL_TRUE if the window's - * context is an OpenGL debug context, or @c GL_FALSE otherwise. + * The `GLFW_OPENGL_DEBUG_CONTEXT` parameter is `GL_TRUE` if the window's + * context is an OpenGL debug context, or `GL_FALSE` otherwise. * - * The @c GLFW_OPENGL_PROFILE parameter indicates the OpenGL profile used by the - * context. This is @c GLFW_OPENGL_CORE_PROFILE or @c - * GLFW_OPENGL_COMPAT_PROFILE if the context uses a known profile, or @c - * GLFW_OPENGL_NO_PROFILE if the OpenGL profile is unknown or the context is - * for another client API. + * The `GLFW_OPENGL_PROFILE` parameter 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_NO_PROFILE` if the + * OpenGL profile is unknown or the context is for another client API. * - * The @c GLFW_CONTEXT_ROBUSTNESS parameter indicates the robustness strategy - * used by the context. This is @c GLFW_LOSE_CONTEXT_ON_RESET or @c - * GLFW_NO_RESET_NOTIFICATION if the window's context supports robustness, or - * @c GLFW_NO_ROBUSTNESS otherwise. + * The `GLFW_CONTEXT_ROBUSTNESS` parameter 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. */ GLFWAPI int glfwGetWindowParam(GLFWwindow* window, int param); @@ -1337,7 +1335,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); /*! @brief Sets the position callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window */ @@ -1345,7 +1343,7 @@ GLFWAPI void glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun /*! @brief Sets the size callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window * @@ -1355,7 +1353,7 @@ GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbf /*! @brief Sets the close callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window * @@ -1366,14 +1364,14 @@ GLFWAPI void glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbf * @remarks Calling @ref glfwDestroyWindow does not cause this callback to be * called. * - * @remarks Mac OS X: Selecting Quit from the application menu will + * @remarks **Mac OS X:** Selecting Quit from the application menu will * trigger the close callback for all windows. */ GLFWAPI void glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun); /*! @brief Sets the refresh callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window * @@ -1389,7 +1387,7 @@ GLFWAPI void glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshf /*! @brief Sets the focus callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window * @@ -1399,7 +1397,7 @@ GLFWAPI void glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun c /*! @brief Sets the iconify callback for the specified window. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup window * @@ -1434,9 +1432,9 @@ GLFWAPI void glfwWaitEvents(void); /*! @brief Returns the value of an input option for the specified window. * @param[in] window The window to query. * @param[in] mode One of the following: - * @arg @c GLFW_CURSOR_MODE Sets the cursor mode. - * @arg @c GLFW_STICKY_KEYS Sets whether sticky keys are enabled. - * @arg @c GLFW_STICKY_MOUSE_BUTTONS Sets whether sticky mouse buttons are enabled. + * @arg `GLFW_CURSOR_MODE` Sets the cursor mode. + * @arg `GLFW_STICKY_KEYS` Sets whether sticky keys are enabled. + * @arg `GLFW_STICKY_MOUSE_BUTTONS` Sets whether sticky mouse buttons are enabled. * @ingroup input * * @sa glfwSetInputMode @@ -1445,15 +1443,15 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); /*! @brief Sets an input option for the specified window. * @param[in] window The window whose input mode to set. - * @param[in] mode One of @c GLFW_CURSOR_MODE, @c GLFW_STICKY_KEYS or @c - * GLFW_STICKY_MOUSE_BUTTONS. + * @param[in] mode One of `GLFW_CURSOR_MODE`, `GLFW_STICKY_KEYS` or + * `GLFW_STICKY_MOUSE_BUTTONS`. * @param[in] value The new value of the specified input mode. * @ingroup input * - * @bug Windows: The @ref GLFW_CURSOR_HIDDEN value of @ref + * @bug **Windows:** The @ref GLFW_CURSOR_HIDDEN value of @ref * GLFW_CURSOR_MODE is not yet implemented. * - * @bug Mac OS X: The @ref GLFW_CURSOR_HIDDEN value of @ref + * @bug **Mac OS X:** The @ref GLFW_CURSOR_HIDDEN value of @ref * GLFW_CURSOR_MODE is not yet implemented. * * @sa glfwGetInputMode @@ -1463,8 +1461,8 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); /*! @brief Returns the last reported state of a keyboard key for the specified * window. * @param[in] window The desired window. - * @param[in] key The desired @link keys keyboard key @endlink. - * @return One of @c GLFW_PRESS or @c GLFW_RELEASE. + * @param[in] key The desired [keyboard key](@ref keys). + * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. * @ingroup input */ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); @@ -1472,8 +1470,8 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); /*! @brief Returns the last reported state of a mouse button for the specified * window. * @param[in] window The desired window. - * @param[in] button The desired @link buttons mouse buttons @endlink. - * @return One of @c GLFW_PRESS or @c GLFW_RELEASE. + * @param[in] button The desired [mouse button](@ref buttons). + * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. * @ingroup input */ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); @@ -1482,9 +1480,9 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * area of the window. * @param[in] window The desired window. * @param[out] xpos The cursor x-coordinate, relative to the left edge of the - * client area, or @c NULL. + * client area, or `NULL`. * @param[out] ypos The cursor y-coordinate, relative to the to top edge of the - * client area, or @c NULL. + * client area, or `NULL`. * @ingroup input * * @sa glfwSetCursorPos @@ -1494,9 +1492,9 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, int* xpos, int* ypos); /*! @brief Sets the position of the cursor, relative to the client area of the window. * @param[in] window The desired window. * @param[in] xpos The desired x-coordinate, relative to the left edge of the - * client area, or @c NULL. + * client area, or `NULL`. * @param[in] ypos The desired y-coordinate, relative to the top edge of the - * client area, or @c NULL. + * client area, or `NULL`. * @ingroup input * * @note The specified window must be focused. @@ -1507,19 +1505,19 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, int xpos, int ypos); /*! @brief Sets the key callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new key callback, or @c NULL to remove the currently + * @param[in] cbfun The new key callback, or `NULL` to remove the currently * set callback. * @ingroup input * - * @remarks The key callback deals with physical keys, with @link keys tokens - * @endlink named after their use on the standard US keyboard layout. If you + * @remarks The key callback deals with physical keys, with [key tokens](@ref + * keys) named after their use on the standard US keyboard layout. If you * want to input text, use the Unicode character callback instead. */ GLFWAPI void glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); /*! @brief Sets the Unicode character callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup input * @@ -1530,7 +1528,7 @@ GLFWAPI void glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); /*! @brief Sets the mouse button callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup input */ @@ -1538,7 +1536,7 @@ GLFWAPI void glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun c /*! @brief Sets the cursor position callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup input * @@ -1549,7 +1547,7 @@ GLFWAPI void glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun /*! @brief Sets the cursor enter/exit callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new callback, or @c NULL to remove the currently set + * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. * @ingroup input */ @@ -1557,7 +1555,7 @@ GLFWAPI void glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun c /*! @brief Sets the scroll callback. * @param[in] window The window whose callback to set. - * @param[in] cbfun The new scroll callback, or @c NULL to remove the currently + * @param[in] cbfun The new scroll callback, or `NULL` to remove the currently * set callback. * @ingroup input * @@ -1579,7 +1577,7 @@ GLFWAPI int glfwGetJoystickParam(int joy, int param); * @param[in] joy The joystick to query. * @param[out] axes The array to hold the values. * @param[in] numaxes The size of the provided array. - * @return The number of values written to @p axes, or zero if an error + * @return The number of values written to `axes,` or zero if an error * occurred. * @ingroup input */ @@ -1589,7 +1587,7 @@ GLFWAPI int glfwGetJoystickAxes(int joy, float* axes, int numaxes); * @param[in] joy The joystick to query. * @param[out] buttons The array to hold the values. * @param[in] numbuttons The size of the provided array. - * @return The number of values written to @p buttons, or zero if an error + * @return The number of values written to `buttons,` or zero if an error * occurred. * @ingroup input */ @@ -1597,7 +1595,7 @@ GLFWAPI int glfwGetJoystickButtons(int joy, unsigned char* buttons, int numbutto /*! @brief Returns the name of the specified joystick. * @param[in] joy The joystick to query. - * @return The UTF-8 encoded name of the joystick, or @c NULL if the joystick + * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick * is not present. * @ingroup input * @@ -1619,7 +1617,7 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); /*! @brief Retrieves the contents of the clipboard as a string. * @param[in] window The window that will request the clipboard contents. - * @return The contents of the clipboard as a UTF-8 encoded string, or @c NULL + * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` * if an error occurred. * @ingroup clipboard * @@ -1654,7 +1652,7 @@ GLFWAPI double glfwGetTime(void); GLFWAPI void glfwSetTime(double time); /*! @brief Makes the context of the specified window current for this thread. - * @param[in] window The window whose context to make current, or @c NULL to + * @param[in] window The window whose context to make current, or `NULL` to * detach the current context. * @ingroup context * @@ -1667,7 +1665,7 @@ GLFWAPI void glfwSetTime(double time); GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); /*! @brief Returns the window whose context is current on this thread. - * @return The window whose context is current, or @c NULL if no window's + * @return The window whose context is current, or `NULL` if no window's * context is current. * @ingroup context * @@ -1700,7 +1698,7 @@ GLFWAPI void glfwSwapInterval(int interval); /*! @brief Checks whether the specified extension is available. * @param[in] extension The ASCII encoded name of the extension. - * @return @c GL_TRUE if the extension is available, or @c FALSE otherwise. + * @return `GL_TRUE` if the extension is available, or `GL_FALSE` otherwise. * @ingroup context * * @remarks This function may be called from secondary threads. @@ -1713,7 +1711,7 @@ GLFWAPI int glfwExtensionSupported(const char* extension); /*! @brief Returns the address of the specified client API function for the * current context. * @param[in] procname The ASCII encoded name of the function. - * @return The address of the function, or @c NULL if the function is + * @return The address of the function, or `NULL` if the function is * unavailable. * @ingroup context * diff --git a/include/GL/glfw3native.h b/include/GL/glfw3native.h index 6a2c1d15..a229f566 100644 --- a/include/GL/glfw3native.h +++ b/include/GL/glfw3native.h @@ -41,24 +41,24 @@ extern "C" { /*! @defgroup native Native access * - * By using the native API, you assert that you know what you are - * doing and how to fix problems caused by using it. If you don't, you - * shouldn't be using it. + * **By using the native API, you assert that you know what you are doing and + * how to fix problems caused by using it. If you don't, you shouldn't be + * using it.** * * Before the inclusion of @ref glfw3native.h, you must define exactly one * window API macro and exactly one context API macro. Failure to do this * will cause a compile-time error. * * The available window API macros are: - * @arg @c GLFW_EXPOSE_NATIVE_WIN32 - * @arg @c GLFW_EXPOSE_NATIVE_COCOA - * @arg @c GLFW_EXPOSE_NATIVE_X11 + * * `GLFW_EXPOSE_NATIVE_WIN32` + * * `GLFW_EXPOSE_NATIVE_COCOA` + * * `GLFW_EXPOSE_NATIVE_X11` * * The available context API macros are: - * @arg @c GLFW_EXPOSE_NATIVE_WGL - * @arg @c GLFW_EXPOSE_NATIVE_NSGL - * @arg @c GLFW_EXPOSE_NATIVE_GLX - * @arg @c GLFW_EXPOSE_NATIVE_EGL + * * `GLFW_EXPOSE_NATIVE_WGL` + * * `GLFW_EXPOSE_NATIVE_NSGL` + * * `GLFW_EXPOSE_NATIVE_GLX` + * * `GLFW_EXPOSE_NATIVE_EGL` * * These macros select which of the native access functions are declared and * which platform-specific headers to include. It is then up your (by @@ -103,71 +103,71 @@ extern "C" { *************************************************************************/ #if defined(GLFW_EXPOSE_NATIVE_WIN32) -/*! @brief Returns the @c HWND of the specified window. - * @return The @c HWND of the specified window. +/*! @brief Returns the `HWND` of the specified window. + * @return The `HWND` of the specified window. * @ingroup native */ GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_WGL) -/*! @brief Returns the @c HGLRC of the specified window. - * @return The @c HGLRC of the specified window. +/*! @brief Returns the `HGLRC` of the specified window. + * @return The `HGLRC` of the specified window. * @ingroup native */ GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_COCOA) -/*! @brief Returns the @c NSWindow of the specified window. - * @return The @c NSWindow of the specified window. +/*! @brief Returns the `NSWindow` of the specified window. + * @return The `NSWindow` of the specified window. * @ingroup native */ GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_NSGL) -/*! @brief Returns the @c NSOpenGLContext of the specified window. - * @return The @c NSOpenGLContext of the specified window. +/*! @brief Returns the `NSOpenGLContext` of the specified window. + * @return The `NSOpenGLContext` of the specified window. * @ingroup native */ GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_X11) -/*! @brief Returns the @c Display used by GLFW. - * @return The @c Display used by GLFW. +/*! @brief Returns the `Display` used by GLFW. + * @return The `Display` used by GLFW. * @ingroup native */ GLFWAPI Display* glfwGetX11Display(void); -/*! @brief Returns the @c Window of the specified window. - * @return The @c Window of the specified window. +/*! @brief Returns the `Window` of the specified window. + * @return The `Window` of the specified window. * @ingroup native */ GLFWAPI Window glfwGetX11Window(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_GLX) -/*! @brief Returns the @c GLXContext of the specified window. - * @return The @c GLXContext of the specified window. +/*! @brief Returns the `GLXContext` of the specified window. + * @return The `GLXContext` of the specified window. * @ingroup native */ GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); #endif #if defined(GLFW_EXPOSE_NATIVE_EGL) -/*! @brief Returns the @c EGLDisplay used by GLFW. - * @return The @c EGLDisplay used by GLFW. +/*! @brief Returns the `EGLDisplay` used by GLFW. + * @return The `EGLDisplay` used by GLFW. * @ingroup native */ GLFWAPI EGLDisplay glfwGetEGLDisplay(void); -/*! @brief Returns the @c EGLContext of the specified window. - * @return The @c EGLContext of the specified window. +/*! @brief Returns the `EGLContext` of the specified window. + * @return The `EGLContext` of the specified window. * @ingroup native */ GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); -/*! @brief Returns the @c EGLSurface of the specified window. - * @return The @c EGLSurface of the specified window. +/*! @brief Returns the `EGLSurface` of the specified window. + * @return The `EGLSurface` of the specified window. * @ingroup native */ GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window); diff --git a/src/internal.h b/src/internal.h index 753ef239..9c49a5f0 100644 --- a/src/internal.h +++ b/src/internal.h @@ -322,7 +322,7 @@ extern _GLFWlibrary _glfw; //======================================================================== /*! @brief Initializes the platform-specific part of the library. - * @return @c GL_TRUE if successful, or @c GL_FALSE if an error occurred. + * @return `GL_TRUE` if successful, or `GL_FALSE` if an error occurred. * @ingroup platform */ int _glfwPlatformInit(void); @@ -526,7 +526,7 @@ GLFWglproc _glfwPlatformGetProcAddress(const char* procname); /*! @brief Notifies shared code of a window focus event. * @param[in] window The window that received the event. - * @param[in] focused @c GL_TRUE if the window received focus, or @c GL_FALSE + * @param[in] focused `GL_TRUE` if the window received focus, or `GL_FALSE` * if it lost focus. * @ingroup event */ @@ -550,7 +550,7 @@ void _glfwInputWindowSize(_GLFWwindow* window, int width, int height); /*! @brief Notifies shared code of a window iconification event. * @param[in] window The window that received the event. - * @param[in] iconified @c GL_TRUE if the window was iconified, or @c GL_FALSE + * @param[in] iconified `GL_TRUE` if the window was iconified, or `GL_FALSE` * if it was restored. * @ingroup event */ @@ -558,7 +558,7 @@ void _glfwInputWindowIconify(_GLFWwindow* window, int iconified); /*! @brief Notifies shared code of a window show/hide event. * @param[in] window The window that received the event. - * @param[in] visible @c GL_TRUE if the window was shown, or @c GL_FALSE if it + * @param[in] visible `GL_TRUE` if the window was shown, or `GL_FALSE` if it * was hidden. * @ingroup event */ @@ -618,8 +618,8 @@ void _glfwInputCursorMotion(_GLFWwindow* window, int x, int y); /*! @brief Notifies shared code of a cursor enter/leave event. * @param[in] window The window that received the event. - * @param[in] entered @c GL_TRUE if the cursor entered the client area of the - * window, or @c GL_FALSE if it left it. + * @param[in] entered `GL_TRUE` if the cursor entered the client area of the + * window, or `GL_FALSE` if it left it. * @ingroup event */ void _glfwInputCursorEnter(_GLFWwindow* window, int entered); @@ -630,7 +630,7 @@ void _glfwInputMonitorChange(void); /*! @brief Notifies shared code of an error. * @param[in] error The error code most suitable for the error. - * @param[in] format The @c printf style format string of the error + * @param[in] format The `printf` style format string of the error * description. * @ingroup event */ @@ -659,20 +659,20 @@ void _glfwSplitBPP(int bpp, int* red, int* green, int* blue); /*! @brief Searches an extension string for the specified extension. * @param[in] string The extension string to search. * @param[in] extensions The extension to search for. - * @return @c GL_TRUE if the extension was found, or @c GL_FALSE otherwise. + * @return `GL_TRUE` if the extension was found, or `GL_FALSE` otherwise. * @ingroup utility */ int _glfwStringInExtensionString(const char* string, const GLubyte* extensions); /*! @brief Checks and reads back properties from the current context. - * @return @c GL_TRUE if successful, or @c GL_FALSE if the context is unusable. + * @return `GL_TRUE` if successful, or `GL_FALSE` if the context is unusable. * @ingroup utility */ GLboolean _glfwRefreshContextParams(void); /*! @brief Checks whether the desired context properties are valid. * @param[in] wndconfig The context properties to check. - * @return @c GL_TRUE if the context properties are valid, or @c GL_FALSE + * @return `GL_TRUE` if the context properties are valid, or `GL_FALSE` * otherwise. * @ingroup utility * @@ -685,8 +685,8 @@ GLboolean _glfwIsValidContextConfig(_GLFWwndconfig* wndconfig); /*! @brief Checks whether the current context fulfils the specified hard * constraints. * @param[in] wndconfig The desired context properties. - * @return @c GL_TRUE if the context fulfils the hard constraints, or @c - * GL_FALSE otherwise. + * @return `GL_TRUE` if the context fulfils the hard constraints, or `GL_FALSE` + * otherwise. * @ingroup utility */ GLboolean _glfwIsValidContext(_GLFWwndconfig* wndconfig);