mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-09-19 21:32:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify difference between time and timer in docs

Browse Source
This commit is contained in:
Camilla Löwy 2019-05-20 17:13:09 +02:00
parent 22a6c02a4c
commit bb6945a18a
2 changed files with 29 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/input.dox
View File

@ -864,28 +864,29 @@ GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
double seconds = glfwGetTime(); double seconds = glfwGetTime();
@endcode @endcode
It returns the number of seconds since the timer was started when the library It returns the number of seconds since the library was initialized with @ref
was initialized with @ref glfwInit. The platform-specific time sources used glfwInit. The platform-specific time sources used typically have micro- or
usually have micro- or nanosecond resolution. nanosecond resolution.
You can modify the reference time with @ref glfwSetTime. You can modify the base time with @ref glfwSetTime.
@code @code
glfwSetTime(4.0); glfwSetTime(4.0);
@endcode @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 You can also access the raw timer used to implement the functions above,
seconds, with @ref glfwGetTimerValue. with @ref glfwGetTimerValue.
@code @code
uint64_t value = glfwGetTimerValue(); uint64_t value = glfwGetTimerValue();
@endcode @endcode
The frequency of the raw timer varies depending on what time sources are This value is in 1 / frequency seconds. The frequency of the raw
available on the machine. You can query its frequency, in Hz, with @ref timer varies depending on the operating system and hardware. You can query the
glfwGetTimerFrequency. frequency, in Hz, with @ref glfwGetTimerFrequency.
@code @code
uint64_t freqency = glfwGetTimerFrequency(); uint64_t freqency = glfwGetTimerFrequency();

30
include/GLFW/glfw3.h
View File

@ -5066,23 +5066,26 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
*/ */
GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); 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 * This function returns the current GLFW time, in seconds. Unless the time
* been set using @ref glfwSetTime, the timer measures time elapsed since GLFW * has been set using @ref glfwSetTime it measures time elapsed since GLFW was
* was initialized. * 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 * 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 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic
* time source on each supported platform. * 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. * [error](@ref error_handling) occurred.
* *
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED. * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
* *
* @thread_safety This function may be called from any thread. Reading and * @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. * externally synchronized with calls to @ref glfwSetTime.
* *
* @sa @ref time * @sa @ref time
@ -5093,23 +5096,26 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
*/ */
GLFWAPI double glfwGetTime(void); 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 * This function sets the current GLFW time, in seconds. The value must be
* up from that value. The value must be a positive finite number less than * a positive finite number less than or equal to 18446744073.0, which is
* or equal to 18446744073.0, which is approximately 584.5 years. * 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. * @param[in] time The new value, in seconds.
* *
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_VALUE. * GLFW_INVALID_VALUE.
* *
* @remark The upper limit of the timer is calculated as * @remark The upper limit of GLFW time is calculated as
* floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
* storing nanoseconds in 64 bits. The limit may be increased in the future. * 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 * @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. * externally synchronized with calls to @ref glfwGetTime.
* *
* @sa @ref time * @sa @ref time