From bb6945a18ad4a33a2d2a0c9874da11e699978ed2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Mon, 20 May 2019 17:13:09 +0200 Subject: [PATCH] Clarify difference between time and timer in docs --- docs/input.dox | 21 +++++++++++---------- include/GLFW/glfw3.h | 30 ++++++++++++++++++------------ 2 files changed, 29 insertions(+), 22 deletions(-) diff --git a/docs/input.dox b/docs/input.dox index 4c07a818..eb0244a7 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -864,28 +864,29 @@ GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. double seconds = glfwGetTime(); @endcode -It returns the number of seconds since the timer was started when the library -was initialized with @ref glfwInit. The platform-specific time sources used -usually have micro- or nanosecond resolution. +It returns the number of seconds since the library was initialized with @ref +glfwInit. The platform-specific time sources used typically have micro- or +nanosecond resolution. -You can modify the reference time with @ref glfwSetTime. +You can modify the base time with @ref glfwSetTime. @code glfwSetTime(4.0); @endcode -This sets the timer to the specified time, in seconds. +This sets the time to the specified time, in seconds, and it continues to count +from there. -You can also access the raw timer value, measured in 1 / frequency -seconds, with @ref glfwGetTimerValue. +You can also access the raw timer used to implement the functions above, +with @ref glfwGetTimerValue. @code uint64_t value = glfwGetTimerValue(); @endcode -The frequency of the raw timer varies depending on what time sources are -available on the machine. You can query its frequency, in Hz, with @ref -glfwGetTimerFrequency. +This value is in 1 / frequency seconds. The frequency of the raw +timer varies depending on the operating system and hardware. You can query the +frequency, in Hz, with @ref glfwGetTimerFrequency. @code uint64_t freqency = glfwGetTimerFrequency(); diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index b4428857..9cedc766 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -5066,23 +5066,26 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); */ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); -/*! @brief Returns the value of the GLFW timer. +/*! @brief Returns the GLFW time. * - * This function returns the value of the GLFW timer. Unless the timer has - * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW - * was initialized. + * This function returns the current GLFW time, in seconds. Unless the time + * has been set using @ref glfwSetTime it measures time elapsed since GLFW was + * initialized. + * + * This function and @ref glfwSetTime are helper functions on top of @ref + * glfwGetTimerFrequency and @ref glfwGetTimerValue. * * The resolution of the timer is system dependent, but is usually on the order * of a few micro- or nanoseconds. It uses the highest-resolution monotonic * time source on each supported platform. * - * @return The current value, in seconds, or zero if an + * @return The current time, in seconds, or zero if an * [error](@ref error_handling) occurred. * * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. * * @thread_safety This function may be called from any thread. Reading and - * writing of the internal timer offset is not atomic, so it needs to be + * writing of the internal base time is not atomic, so it needs to be * externally synchronized with calls to @ref glfwSetTime. * * @sa @ref time @@ -5093,23 +5096,26 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); */ GLFWAPI double glfwGetTime(void); -/*! @brief Sets the GLFW timer. +/*! @brief Sets the GLFW time. * - * This function sets the value of the GLFW timer. It then continues to count - * up from that value. The value must be a positive finite number less than - * or equal to 18446744073.0, which is approximately 584.5 years. + * This function sets the current GLFW time, in seconds. The value must be + * a positive finite number less than or equal to 18446744073.0, which is + * approximately 584.5 years. + * + * This function and @ref glfwGetTime are helper functions on top of @ref + * glfwGetTimerFrequency and @ref glfwGetTimerValue. * * @param[in] time The new value, in seconds. * * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref * GLFW_INVALID_VALUE. * - * @remark The upper limit of the timer is calculated as + * @remark The upper limit of GLFW time is calculated as * floor((264 - 1) / 109) and is due to implementations * storing nanoseconds in 64 bits. The limit may be increased in the future. * * @thread_safety This function may be called from any thread. Reading and - * writing of the internal timer offset is not atomic, so it needs to be + * writing of the internal base time is not atomic, so it needs to be * externally synchronized with calls to @ref glfwGetTime. * * @sa @ref time