From 5fd409b67981fdb9bde7d3fef19320597472ea2c Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 5 Jun 2013 17:53:13 +0200 Subject: [PATCH] Documentation work. --- include/GLFW/glfw3.h | 178 +++++++++++++++++++++++-------------------- 1 file changed, 96 insertions(+), 82 deletions(-) diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index d2709937..4ea1b69c 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -951,8 +951,8 @@ GLFWAPI const char* glfwGetVersionString(void); * * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @remarks This function may be called before @ref glfwInit. * @@ -974,8 +974,8 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun); * This function returns an array of handles for all currently connected * monitors. * - * @param[out] count The size of the returned array, or zero if an error - * occurred. + * @param[out] count Where to store the size of the returned array. This is + * set to zero if an error occurred. * @return An array of monitor handles, or `NULL` if an error occurred. * * @note The returned array is allocated and freed by GLFW. You should not @@ -1010,8 +1010,8 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); * corner of the specified monitor. * * @param[in] monitor The monitor to query. - * @param[out] xpos The monitor x-coordinate. - * @param[out] ypos The monitor y-coordinate. + * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. + * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. * * @ingroup monitor */ @@ -1023,8 +1023,10 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); * specified monitor. * * @param[in] monitor The monitor to query. - * @param[out] width The width, in mm, of the monitor's display - * @param[out] height The height, in mm, of the monitor's display. + * @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`. * * @note Some operating systems do not provide accurate information, either * because the monitor's EDID data is incorrect, or because the driver does not @@ -1058,7 +1060,8 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); * * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @bug This callback is not yet called on monitor configuration changes. * @@ -1074,8 +1077,8 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); * product of width and height). * * @param[in] monitor The monitor to query. - * @param[out] count The number of video modes in the returned array, or zero - * if an error occurred. + * @param[out] count Where to store the number of video modes in the returned + * array. This is set to zero if an error occurred. * @return An array of video modes, or `NULL` if an error occurred. * * @note The returned array is allocated and freed by GLFW. You should not @@ -1125,7 +1128,7 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); * This function retrieves the current gamma ramp of the specified monitor. * * @param[in] monitor The monitor to query. - * @return The current gamma ramp. + * @return The current gamma ramp, or `NULL` if an error occurred. * * @note The value arrays of the returned ramp are allocated and freed by GLFW. * You should not free them yourself. @@ -1199,6 +1202,12 @@ GLFWAPI void glfwWindowHint(int target, int hint); * attributes of the created window and context, use queries like @ref * glfwGetWindowAttrib and @ref glfwGetWindowSize. * + * To create the window at a specific position, make it initially invisible + * using the `GLFW_VISIBLE` window hint, set its position and then show it. + * + * If a fullscreen window is active, the screensaver is prohibited from + * starting. + * * @param[in] width The desired width, in screen coordinates, of the window. * This must be greater than zero. * @param[in] height The desired height, in screen coordinates, of the window. @@ -1210,13 +1219,6 @@ GLFWAPI void glfwWindowHint(int target, int hint); * to not share resources. * @return The handle of the created window, or `NULL` if an error occurred. * - * @remarks To create the window at a specific position, make it initially - * invisible using the `GLFW_VISIBLE` window hint, set its position and then - * show it. - * - * @remarks If a fullscreen window is active, the screensaver is prohibited - * from starting. - * * @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. @@ -1302,10 +1304,10 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); * upper-left corner of the client area of the specified window. * * @param[in] window The window to query. - * @param[out] xpos The x-coordinate of the upper-left corner of the client area. - * @param[out] ypos The y-coordinate of the upper-left corner of the client area. - * - * @remarks Either or both coordinate arguments may be `NULL`. + * @param[out] xpos Where to store the x-coordinate of the upper-left corner of + * the client area, or `NULL`. + * @param[out] ypos Where to store the y-coordinate of the upper-left corner of + * the client area, or `NULL`. * * @sa glfwSetWindowPos * @@ -1318,16 +1320,16 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); * This function sets the position, in screen coordinates, of the upper-left * corner of the client area of the window. * - * If it is a full screen window, this function does nothing. + * If the specified window is a full screen window, this function does nothing. + * + * If you wish to set an initial window position you should create a hidden + * window (using @ref glfwWindowHint and `GLFW_VISIBLE`), set its position and + * then show it. * * @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. * - * @remarks If you wish to set an initial window position you should create - * 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 * will confuse and annoy the user. * @@ -1351,8 +1353,10 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); * of the specified window. * * @param[in] window The window whose size to retrieve. - * @param[out] width The width of the client area. - * @param[out] height The height of the client area. + * @param[out] width Where to store the width, in screen coordinates, of the + * client area, or `NULL`. + * @param[out] height Where to store the height, in screen coordinates, of the + * client area, or `NULL`. * * @sa glfwSetWindowSize * @@ -1390,8 +1394,10 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); * specified window. * * @param[in] window The window whose framebuffer to query. - * @param[out] width The width of the framebuffer. - * @param[out] height The height of the framebuffer. + * @param[out] width Where to store the width, in pixels, of the framebuffer, + * or `NULL`. + * @param[out] height Where to store the height, in pixels, of the framebuffer, + * or `NULL`. * * @sa glfwSetFramebufferSizeCallback * @@ -1528,8 +1534,8 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup window */ @@ -1544,8 +1550,8 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup window */ @@ -1560,14 +1566,13 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind * The close flag is set before this callback is called, but you can modify it * at any time with @ref glfwSetWindowShouldClose. * + * The close callback is not triggered by @ref glfwDestroyWindow. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @remarks Calling @ref glfwDestroyWindow does not cause this callback to be - * called. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @remarks **Mac OS X:** Selecting Quit from the application menu will * trigger the close callback for all windows. @@ -1589,7 +1594,8 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @note On compositing window systems such as Aero, Compiz or Aqua, where the * window contents are saved off-screen, this callback may be called only very @@ -1612,8 +1618,8 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup window */ @@ -1627,8 +1633,8 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup window */ @@ -1642,8 +1648,8 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup window */ @@ -1655,12 +1661,12 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window * and then returns immediately. Processing events will cause the window and * input callbacks associated with those events to be called. * + * This function is not required for joystick input to work. + * * @par New in GLFW 3 * This function is no longer called by @ref glfwSwapBuffers. You need to call * it or @ref glfwWaitEvents yourself. * - * @remarks This function is not required for joystick input to work. - * * @note This function may only be called from the main thread. * * @note This function may not be called from a callback. @@ -1686,7 +1692,7 @@ GLFWAPI void glfwPollEvents(void); * without a callback having been called even if you are monitoring all * callbacks. * - * @remarks This function is not required for joystick input to work. + * This function is not required for joystick input to work. * * @note This function may only be called from the main thread. * @@ -1802,10 +1808,10 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); * coordinates, but fails for negative ones. * * @param[in] window The desired window. - * @param[out] xpos The cursor x-coordinate, relative to the left edge of the - * client area, or `NULL`. - * @param[out] ypos The cursor y-coordinate, relative to the to top edge of the - * client area, or `NULL`. + * @param[out] xpos Where to store the cursor x-coordinate, relative to the + * left edge of the client area, or `NULL`. + * @param[out] ypos Where to store the cursor y-coordinate, relative to the to + * top edge of the client area, or `NULL`. * * @sa glfwSetCursorPos * @@ -1842,8 +1848,8 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); * * The key functions deal with physical keys, with layout independent * [key tokens](@ref keys) named after their values in the standard US keyboard - * layout. If you want to input text, use the [character callback](@ref - * glfwSetCharCallback) instead. + * layout. If you want to input text, use the + * [character callback](@ref glfwSetCharCallback) instead. * * 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 @@ -1854,8 +1860,8 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); * @param[in] window The window whose callback to set. * @param[in] cbfun The new key callback, or `NULL` to remove the currently * set callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1873,8 +1879,8 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1894,8 +1900,8 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1910,8 +1916,8 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1926,8 +1932,8 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor * @param[in] window The window whose callback to set. * @param[in] cbfun The new callback, or `NULL` to remove the currently set * callback. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1939,14 +1945,14 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu * called when a scrolling device is used, such as a mouse wheel or scrolling * area of a touchpad. * + * The scroll callback receives all scrolling input, like that from a mouse + * wheel or a touchpad scrolling area. + * * @param[in] window The window whose callback to set. * @param[in] cbfun The new scroll callback, or `NULL` to remove the currently * set callback. - * - * @remarks This receives all scrolling input, like that from a mouse wheel or - * a touchpad scrolling area. - * - * @return The previously set callback, or `NULL` if an error occurred. + * @return The previously set callback, or `NULL` if no callback was set or an + * error occurred. * * @ingroup input */ @@ -1964,9 +1970,13 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb GLFWAPI int glfwJoystickPresent(int joy); /*! @brief Returns the values of all axes of the specified joystick. + * + * This function returns the values of all axes of the specified joystick. + * * @param[in] joy The joystick to query. - * @param[out] count The size of the returned array. - * @return An array of axis values, or @c NULL if the joystick is not present. + * @param[out] count Where to store the size of the returned array. This is + * set to zero if an error occurred. + * @return An array of axis values, or `NULL` if the joystick is not present. * * @note The returned array is allocated and freed by GLFW. You should not * free it yourself. @@ -1979,9 +1989,13 @@ GLFWAPI int glfwJoystickPresent(int joy); GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count); /*! @brief Returns the values of all buttons of the specified joystick. + * + * This function returns the values of all buttons of the specified joystick. + * * @param[in] joy The joystick to query. - * @param[out] count The size of the returned array. - * @return An array of axis values, or @c NULL if the joystick is not present. + * @param[out] count Where to store the size of the returned array. This is + * set to zero if an error occurred. + * @return An array of axis values, or `NULL` if the joystick is not present. * * @note The returned array is allocated and freed by GLFW. You should not * free it yourself. @@ -2145,18 +2159,18 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window); * returning from @ref glfwSwapBuffers. This is sometimes called 'vertical * synchronization', 'vertical retrace synchronization' or 'vsync'. * - * @param[in] interval The minimum number of screen updates to wait for - * until the buffers are swapped by @ref glfwSwapBuffers. - * - * @remarks This function may be called from secondary threads. - * - * @remarks Contexts that support either of the `WGL_EXT_swap_control_tear` and + * Contexts that support either of the `WGL_EXT_swap_control_tear` and * `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals, * which allow the driver to swap even if a frame arrives a little bit late. * You can check for the presence of these extensions using @ref * glfwExtensionSupported. For more information about swap tearing, see the * extension specifications. * + * @param[in] interval The minimum number of screen updates to wait for + * until the buffers are swapped by @ref glfwSwapBuffers. + * + * @remarks This function may be called from secondary threads. + * * @note Some GPU drivers do not honor the requested swap interval, either * because of user settings that override the request or due to bugs in the * driver.