From ce8f97c23c4425cbf29397a65d76c6f91e5f92cb Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Sun, 11 Jan 2015 23:33:14 +0100 Subject: [PATCH] Documentation work. Fixes #212. Fixes #420. --- docs/compile.dox | 5 +- docs/intro.dox | 2 +- docs/moving.dox | 2 +- docs/rift.dox | 222 ++++++++++++++++++++++++++----------- docs/window.dox | 5 +- include/GLFW/glfw3.h | 135 ++++++++-------------- include/GLFW/glfw3native.h | 10 +- src/monitor.c | 18 +-- 8 files changed, 228 insertions(+), 171 deletions(-) diff --git a/docs/compile.dox b/docs/compile.dox index 3d1ad213..c7b01e34 100644 --- a/docs/compile.dox +++ b/docs/compile.dox @@ -229,8 +229,9 @@ can lead to severe jitter. `GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement` symbol, which forces the use of the high-performance GPU on Nvidia Optimus -systems. This symbol needs to be exported by the EXE, so the override will not -work if GLFW is built as a DLL. +systems. This symbol needs to be exported by the EXE to be detected by the +driver, so the override will not work if GLFW is built as a DLL. See _Enabling +High Performance Graphics Rendering on Optimus Systems_ for more details. @subsubsection compile_options_egl EGL specific CMake options diff --git a/docs/intro.dox b/docs/intro.dox index d544b36f..8d91783f 100644 --- a/docs/intro.dox +++ b/docs/intro.dox @@ -327,7 +327,7 @@ see which code paths are enabled in a binary. The version string is returned by @ref glfwGetVersionString, a function that may be called regardless of whether GLFW is initialized. -__Do not use the version string__ to find the GLFW library version. The @ref +__Do not use the version string__ to parse the GLFW library version. The @ref glfwGetVersion function already provides the version of the running library binary. diff --git a/docs/moving.dox b/docs/moving.dox index c850ab4c..902aa7d1 100644 --- a/docs/moving.dox +++ b/docs/moving.dox @@ -390,7 +390,7 @@ All explicit support for version of Windows older than XP has been removed. There is no code that actively prevents GLFW 3 from running on these earlier versions, but it uses Win32 functions that those versions lack. -Windows XP was released in 2001, and by now (2013) it has not only +Windows XP was released in 2001, and by now (January 2015) it has not only replaced almost all earlier versions of Windows, but is itself rapidly being replaced by Windows 7 and 8. The MSDN library doesn't even provide documentation for version older than Windows 2000, making it difficult to diff --git a/docs/rift.dox b/docs/rift.dox index d763d477..a13ff77c 100644 --- a/docs/rift.dox +++ b/docs/rift.dox @@ -4,78 +4,174 @@ @tableofcontents -GLFW has no explicit support for the Oculus Rift, but +This guide requires you to use [native access](@ref native) and assumes +a certain level of proficiency with LibOVR, OS specific APIs and your chosen +development environment. It intends only to fill in the gaps between the +[Oculus PC SDK documentation](https://developer.oculus.com/documentation/) and +the GLFW API and is not a replacement for the documentation for those APIs. -This guide requires you to use the [native API](@ref native) and assumes -a certain level of proficiency with system level APIs and the compiler -toolchain. +While GLFW has no explicit support for LibOVR, the Oculus PC SDK library, it is +tested with and tries to interoperate well with it. + +@note Because of the speed of development of the Oculus SDK, this guide may +become outdated before the next release. If this is a local copy from a GLFW +release archive, check the GLFW website for an up-to-date version. -@section rift_init Initializing libOVR and GLFW +@section rift_include Including the LibOVR and GLFW header files -libOVR needs to be initialized before GLFW. This means calling +Both the LibOVR OpenGL header and the GLFW native header need macros telling +them what OS you are building for. Because LibOVR only supports three major +desktop OSes, this can be solved with the canonical predefined macros. + +@code +#if defined(_WIN32) + #define GLFW_EXPOSE_NATIVE_WIN32 + #define GLFW_EXPOSE_NATIVE_WGL + #define OVR_OS_WIN32 +#elif defined(__APPLE__) + #define GLFW_EXPOSE_NATIVE_COCOA + #define GLFW_EXPOSE_NATIVE_NSGL + #define OVR_OS_MAC +#elif defined(__linux__) + #define GLFW_EXPOSE_NATIVE_X11 + #define GLFW_EXPOSE_NATIVE_GLX + #define OVR_OS_LINUX +#else + #error "Platform unsupported" +#endif + +#include +#include + +#include +@endcode + +Both the GLFW and LibOVR headers by default attempt to include the standard +OpenGL `GL/gl.h` header (`OpenGL/gl.h` on OS X). If you wish to use a different +standard header or an [extension loading library](@ref context_glext_auto), +include that header before these. + + +@section rift_init Initializing LibOVR and GLFW + +LibOVR needs to be initialized before GLFW. This means calling at least `ovr_Initialize`, `ovrHmd_Create` and `ovrHmd_ConfigureTracking` before @ref -glfwInit. Similarly, libOVR must be shut down after GLFW. This means calling +glfwInit. Similarly, LibOVR must be shut down after GLFW. This means calling `ovrHmd_Destroy` and `ovr_Shutdown` after @ref glfwTerminate. -@section rift_extend Extend Desktop mode - -@subsection rift_extend_detect Detecting a Rift with GLFW - -If you have an actual Rift connected to your machine you can deduce which GLFW -monitor it corresponds to. Doing this requires you to use the -[native API](@ref native). - - -@subsubsection rift_extend_detect_win32 Detecting a Rift on Windows - -The native display device name of a GLFW monitor, as returned by @ref -glfwGetWin32Monitor, corresponds to the display device name of the detected Rift -as stored, in the `DisplayDeviceName` member of `ovrHmdDesc`. - -@code -int i, count; -GLFWmonitor** monitors = glfwGetMonitors(&count); - -for (i = 0; i < count; i++) -{ - if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0) - return monitors[i]; -} -@endcode - - -@subsubsection rift_extend_detect_osx Detecting a Rift on OS X - -The native display ID of a GLFW monitor, as returned by @ref -glfwGetCocoaMonitor, corresponds to the display ID of the detected Rift, as -stored in the `DisplayId` member of `ovrHmdDesc`. - -@code -int i, count; -GLFWmonitor** monitors = glfwGetMonitors(&count); - -for (i = 0; i < count; i++) -{ - if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId) - return monitors[i]; -} -@endcode - - -@subsubsection rift_extend_detect_x11 Detecting a Rift on X11 - -At the time of writing, the 0.4 Rift SDK does not yet support X11. - - -@subsection rift_extend_create Creating a window and context - -LOL create. - - @section rift_direct Direct HMD mode -LOL direct. +Direct HMD mode is the recommended display mode for new applications, but the +Oculus Rift runtime currently (January 2015) only supports this mode on Windows. +In direct mode the HMD is not detectable as a GLFW monitor. + + +@subsection rift_direct_create Creating a window and context + +If the HMD is in direct mode you can use either a full screen or a windowed mode +window, but full screen is only recommended if there is a monitor that supports +the resolution of the HMD. Due to limitations in LibOVR, the size of the client +area of the window must equal the resolution of the HMD. + +If the resolution of the HMD is much larger than the regular monitor, the window +may be resized by the window manager on creation. One way to avoid this is to +make it undecorated with the [GLFW_DECORATED](@ref window_hints_wnd) window +hint. + + +@subsection rift_direct_attach Attaching the window to the HMD + +Once you have created the window and context, you need to attach the native +handle of the GLFW window to the HMD. + +@code +ovrHmd_AttachToWindow(hmd, glfwGetWin32Window(window), NULL, NULL); +@endcode + + +@section rift_extend Extend Desktop mode + +Extend desktop mode is a legacy display mode, but is still (January 2015) the +only available mode on OS X and Linux, as well as on Windows machines that for +technical reasons do not yet support direct HMD mode. + + +@subsection rift_extend_detect Detecting a HMD with GLFW + +If the HMD is in extend desktop mode you can deduce which GLFW monitor it +corresponds to and create a full screen window on that monitor. + +On Windows, the native display device name of a GLFW monitor corresponds to the +display device name of the detected HMD as stored, in the `DisplayDeviceName` +member of `ovrHmdDesc`. + +On OS X, the native display ID of a GLFW monitor corresponds to the display ID +of the detected HMD, as stored in the `DisplayId` member of `ovrHmdDesc`. + +At the time of writing (January 2015), the Oculus SDK does not support detecting +which monitor corresponds to the HMD in any sane fashion. + +@code +int i, count; +GLFWmonitor** monitors = glfwGetMonitors(&count); + +for (i = 0; i < count; i++) +{ +#if defined(_WIN32) + if (strcmp(glfwGetWin32Monitor(monitors[i]), hmd->DisplayDeviceName) == 0) + return monitors[i]; +#elif defined(__APPLE__) + if (glfwGetCocoaMonitor(monitors[i]) == hmd->DisplayId) + return monitors[i]; +#elif defined(__linux__) +#endif +} +@endcode + + +@subsection rift_extend_create Creating a window and context + +The window is created as a regular full screen window on the found monitor. It +is usually a good idea to create a +[windowed full screen](@ref window_windowed_full_screen) window, as the HMD will +very likely already be set to the correct video mode. However, in extend +desktop mode it behaves like a regular monitor and any supported video mode can +be requested. + +If other monitors are mirroring the HMD and you request a different video mode, +all monitors in the mirroring set will get the new video mode. + + +@section rift_render Rendering to the HMD + +Once the window and context is created, you can render to it the same as any +other application using LibOVR. + +If you wish to use SDK distortion rendering you will need some information from +GLFW to configure the renderer. Below are the parts of the `ovrGLConfig` union +that need to be filled with from GLFW. Note that there are other fields that +also need to be filled for `ovrHmd_ConfigureRendering` to succeed. + +@code + int width, height; + union ovrGLConfig config; + + glfwGetFramebufferSize(window, &width, &height); + + config.OGL.Header.BackBufferSize.w = width; + config.OGL.Header.BackBufferSize.h = height; +#if defined(_WIN32) + config.OGL.Window = glfwGetWin32Window(window); + config.OGL.DC = GetDC(config.OGL.Window); +#elif defined(__APPLE__) +#elif defined(__linux__) + config.OGL.Disp = glfwGetX11Display(); +#endif +@endcode + +When using SDK distortion rendering you should not call @ref glfwSwapBuffers, +as the HMD is updated by `ovrHmd_EndFrame`. */ diff --git a/docs/window.dox b/docs/window.dox index 316a7158..e58cc799 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -481,9 +481,8 @@ glfwGetFramebufferSize(window, &width, &height); glViewport(0, 0, width, height); @endcode -Note that the size of a framebuffer may change independently of the size of -a window, for example if the window is dragged between a regular monitor and -a high-DPI one. +The size of a framebuffer may change independently of the size of a window, for +example if the window is dragged between a regular monitor and a high-DPI one. @subsection window_pos Position diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 9e6ab7f3..c9c41973 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -513,7 +513,8 @@ extern "C" { /*! @brief One of the arguments to the function was an invalid enum value. * * One of the arguments to the function was an invalid enum value, for example - * requesting `GLFW_RED_BITS` with @ref glfwGetWindowAttrib. + * requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref + * glfwGetWindowAttrib. * * @par Analysis * Application programmer error. Fix the offending call. @@ -1099,9 +1100,6 @@ typedef struct GLFWimage * @par History * Added in GLFW 1.0. * - * @par - * __GLFW 3:__ This function no longer registers @ref glfwTerminate with `atexit`. - * * @ingroup init */ GLFWAPI int glfwInit(void); @@ -1174,6 +1172,10 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); * describes the version, platform, compiler and any platform-specific * compile-time options. * + * __Do not use the version string__ to parse the GLFW library version. The + * @ref glfwGetVersion function already provides the version of the running + * library binary. + * * This function always succeeds. * * @return The GLFW version string. @@ -1313,10 +1315,10 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * non-`NULL` size arguments will be set to zero. * * @param[in] monitor The monitor to query. - * @param[out] width Where to store the width, in mm, of the monitor's display - * area, or `NULL`. - * @param[out] height Where to store the height, in mm, of the monitor's - * display area, or `NULL`. + * @param[out] widthMM Where to store the width, in millimetres, of the + * monitor's display area, or `NULL`. + * @param[out] heightMM Where to store the height, in millimetres, of the + * monitor's display area, or `NULL`. * * @note Some systems do not provide accurate monitor size information, either * because the EDID data is incorrect, or because the driver does not report it @@ -1332,7 +1334,7 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * * @ingroup monitor */ -GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* width, int* height); +GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM); /*! @brief Returns the name of the specified monitor. * @@ -1415,8 +1417,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); * Added in GLFW 1.0. * * @par - * __GLFW 3:__ Changed to return a dynamic array of video modes for a specific - * monitor. + * __GLFW 3:__ Changed to return an array of modes for a specific monitor. * * @ingroup monitor */ @@ -1444,7 +1445,7 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); * @sa glfwGetVideoModes * * @par History - * Added in GLFW 3.0. Replaced `glfwGetDesktopMode`. + * Added in GLFW 3.0. Replaces `glfwGetDesktopMode`. * * @ingroup monitor */ @@ -1557,11 +1558,7 @@ GLFWAPI void glfwDefaultWindowHints(void); * @sa glfwDefaultWindowHints * * @par History - * Added in GLFW 2.2. - * - * @par - * __GLFW 3:__ Renamed from `glfwOpenWindowHint`. Hints are no longer reset to - * default values on window creation. + * Added in GLFW 3.0. Replaces `glfwOpenWindowHint`. * * @ingroup window */ @@ -1596,12 +1593,13 @@ GLFWAPI void glfwWindowHint(int target, int hint); * focus, the supported video mode most closely matching the desired video mode * is set for the specified monitor. For more information about full screen * windows, including the creation of so called _windowed full screen_ or - * _borderless full screen_ windows, see @ref window_full_screen. + * _borderless full screen_ windows, see @ref window_windowed_full_screen. * * By default, newly created windows use the placement recommended by the * window system. To create the window at a specific position, make it - * initially invisible using the `GLFW_VISIBLE` window hint, set its - * [position](@ref window_pos) and then [show](@ref window_hide) it. + * initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window + * hint, set its [position](@ref window_pos) and then [show](@ref window_hide) + * it. * * If a full screen window is focused, the screensaver is prohibited from * starting. @@ -1662,10 +1660,7 @@ GLFWAPI void glfwWindowHint(int target, int hint); * @sa glfwDestroyWindow * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwOpenWindow`. Complete signature overhaul. + * Added in GLFW 3.0. Replaces `glfwOpenWindow`. * * @ingroup window */ @@ -1694,10 +1689,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G * @sa glfwCreateWindow * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwCloseWindow`. Added window handle parameter. + * Added in GLFW 3.0. Replaces `glfwCloseWindow`. * * @ingroup window */ @@ -1799,15 +1791,16 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * corner of the client area of the specified windowed mode window. If the * window is a full screen window, this function does nothing. * + * __Do not use this function__ to move an already visible window unless you + * have very good reasons for doing so, as it will confuse and annoy the user. + * + * The window manager may put limits on what positions are allowed. GLFW + * cannot and should not override these limits. + * * @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. * - * @note It is very rarely a good idea to move an already visible window, as it - * will confuse and annoy the user. - * - * @note The window manager may put limits on what positions are allowed. - * * @par Thread Safety * This function may only be called from the main thread. * @@ -1828,7 +1821,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); * * This function retrieves the size, in screen coordinates, of the client area * of the specified window. If you wish to retrieve the size of the - * framebuffer in pixels, see @ref glfwGetFramebufferSize. + * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize. * * Any or all of the size arguments may be `NULL`. If an error occurs, all * non-`NULL` size arguments will be set to zero. @@ -1865,12 +1858,13 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); * the context is unaffected, the bit depths of the framebuffer remain * unchanged. * + * The window manager may put limits on what sizes are allowed. GLFW cannot + * and should not override these limits. + * * @param[in] window The window to resize. * @param[in] width The desired width of the specified window. * @param[in] height The desired height of the specified window. * - * @note The window manager may put limits on what window sizes are allowed. - * * @par Thread Safety * This function may only be called from the main thread. * @@ -2084,11 +2078,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); * @sa @ref window_attribs * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwGetWindowParam`. Added window handle - * parameter. + * Added in GLFW 3.0. Replaces `glfwGetWindowParam` and `glfwGetGLVersion`. * * @ingroup window */ @@ -2156,9 +2146,6 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); * @par History * Added in GLFW 3.0. * - * @par - * __GLFW 3:__ Added window handle parameter. Updated callback signature. - * * @ingroup window */ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun); @@ -2360,9 +2347,6 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window * @par History * Added in GLFW 1.0. * - * @par - * __GLFW 3:__ This function is no longer called by @ref glfwSwapBuffers. - * * @ingroup window */ GLFWAPI void glfwPollEvents(void); @@ -2498,7 +2482,7 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); * @sa glfwGetInputMode * * @par History - * Added in GLFW 3.0. Replaced `glfwEnable` and `glfwDisable`. + * Added in GLFW 3.0. Replaces `glfwEnable` and `glfwDisable`. * * @ingroup input */ @@ -2548,8 +2532,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key); * * This function returns the last state reported for the specified mouse button * to the specified window. The returned state is one of `GLFW_PRESS` or - * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to - * the mouse button callback. + * `GLFW_RELEASE`. * * If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function * `GLFW_PRESS` the first time you call it for a mouse button that was pressed, @@ -2605,11 +2588,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * @sa glfwSetCursorPos * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwGetMousePos`. Added window handle parameter. - * Moved to floating-point coordinates. + * Added in GLFW 3.0. Replaces `glfwGetMousePos`. * * @ingroup input */ @@ -2649,11 +2628,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); * @sa glfwGetCursorPos * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwSetMousePos`. Added window handle parameter. - * Moved to floating-point coordinates. + * Added in GLFW 3.0. Replaces `glfwSetMousePos`. * * @ingroup input */ @@ -2778,9 +2753,8 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); * * When a window loses focus, it will generate synthetic key release events * for all pressed keys. You can tell these events from user-generated events - * by the fact that the synthetic ones are generated after the window has lost - * focus, i.e. `GLFW_FOCUSED` will be false and the focus callback will have - * already been called. + * by the fact that the synthetic ones are generated after the focus loss event + * has been processed, i.e. after the focus callback has been called. * * The scancode of a key is specific to that platform or sometimes even to that * machine. Scancodes are intended to allow users to bind keys that don't have @@ -2892,8 +2866,8 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods * When a window loses focus, it will generate synthetic mouse button release * events for all pressed mouse buttons. You can tell these events from * user-generated events by the fact that the synthetic ones are generated - * after the window has lost focus, i.e. `GLFW_FOCUSED` will be false and the - * focus callback will have already been called. + * after the focus loss event has been processed, i.e. after the focus callback + * has been called. * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set @@ -2935,11 +2909,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo * @sa @ref input_cursor_pos * * @par History - * Added in GLFW 1.0. - * - * @par - * __GLFW 3:__ Renamed from `glfwSetMousePosCallback`. Added window handle - * parameter. Updated callback signature. + * Added in GLFW 3.0. Replaces `glfwSetMousePosCallback`. * * @ingroup input */ @@ -2990,11 +2960,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu * @sa @ref input_scroll * * @par History - * Added in GLFW 2.1. - * - * @par - * __GLFW 3:__ Renamed from `glfwSetMouseWheelCallback`. Added window handle. - * Updated callback signature. + * Added in GLFW 3.0. Replaces `glfwSetMouseWheelCallback`. * * @ingroup input */ @@ -3041,7 +3007,7 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun); * @sa @ref input_joy * * @par History - * Added in GLFW 3.0. Replaced `glfwGetJoystickParam`. + * Added in GLFW 3.0. Replaces `glfwGetJoystickParam`. * * @ingroup input */ @@ -3068,11 +3034,7 @@ GLFWAPI int glfwJoystickPresent(int joy); * @sa @ref input_joy_axis * * @par History - * Added in GLFW 2.2. - * - * @par - * __GLFW 3:__ Renamed from `glfwGetJoystickPos`. Changed to return a dynamic - * array. + * Added in GLFW 3.0. Replaces `glfwGetJoystickPos`. * * @ingroup input */ @@ -3242,7 +3204,7 @@ GLFWAPI void glfwSetTime(double time); * By default, making a context non-current implicitly forces a pipeline flush. * On machines that support `GL_KHR_context_flush_control`, you can control * whether a context performs this flush by setting the - * `GLFW_CONTEXT_RELEASE_BEHAVIOR` [window hint](@ref window_hints_ctx). + * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint. * * @param[in] window The window whose context to make current, or `NULL` to * detach the current context. @@ -3299,8 +3261,7 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void); * Added in GLFW 1.0. * * @par - * __GLFW 3:__ Added window handle parameter. Removed call to @ref - * glfwPollEvents. + * __GLFW 3:__ Added window handle parameter. * * @ingroup window */ @@ -3322,7 +3283,7 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); * extension specifications. * * A context must be current on the calling thread. Calling this function - * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. * * @param[in] interval The minimum number of screen updates to wait for * until the buffers are swapped by @ref glfwSwapBuffers. @@ -3357,7 +3318,7 @@ GLFWAPI void glfwSwapInterval(int interval); * platform-specific context creation API extensions. * * A context must be current on the calling thread. Calling this function - * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. * * As this functions retrieves and searches one or more extension strings each * call, it is recommended that you cache its results if it is going to be used @@ -3388,7 +3349,7 @@ GLFWAPI int glfwExtensionSupported(const char* extension); * by the current context. * * A context must be current on the calling thread. Calling this function - * without a current context will cause a `GLFW_NO_CURRENT_CONTEXT` error. + * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. * * @param[in] procname The ASCII encoded name of the function. * @return The address of the function, or `NULL` if the function is diff --git a/include/GLFW/glfw3native.h b/include/GLFW/glfw3native.h index 881f5049..b3ce7482 100644 --- a/include/GLFW/glfw3native.h +++ b/include/GLFW/glfw3native.h @@ -40,9 +40,9 @@ extern "C" { /*! @defgroup native Native access * - * **By using the native API, you assert that you know what you're doing and - * how to fix problems caused by using it. If you don't, you shouldn't be - * using it.** + * **By using the native access functions you assert that you know what you're + * doing and how to fix problems caused by using them. If you don't, you + * shouldn't be using them.** * * Before the inclusion of @ref glfw3native.h, you must define exactly one * window system API macro and exactly one context creation API macro. Failure @@ -87,7 +87,7 @@ extern "C" { #include #include #else - #error "No window API specified" + #error "No window API selected" #endif #if defined(GLFW_EXPOSE_NATIVE_WGL) @@ -99,7 +99,7 @@ extern "C" { #elif defined(GLFW_EXPOSE_NATIVE_EGL) #include #else - #error "No context API specified" + #error "No context API selected" #endif diff --git a/src/monitor.c b/src/monitor.c index ad353532..1ab57489 100644 --- a/src/monitor.c +++ b/src/monitor.c @@ -321,21 +321,21 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* handle, int* xpos, int* ypos) _glfwPlatformGetMonitorPos(monitor, xpos, ypos); } -GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* handle, int* width, int* height) +GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* handle, int* widthMM, int* heightMM) { _GLFWmonitor* monitor = (_GLFWmonitor*) handle; - if (width) - *width = 0; - if (height) - *height = 0; + if (widthMM) + *widthMM = 0; + if (heightMM) + *heightMM = 0; _GLFW_REQUIRE_INIT(); - if (width) - *width = monitor->widthMM; - if (height) - *height = monitor->heightMM; + if (widthMM) + *widthMM = monitor->widthMM; + if (heightMM) + *heightMM = monitor->heightMM; } GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* handle)