mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 13:04:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify difference between time and timer in docs

Browse Source 
(cherry picked from commit bb6945a18a)
This commit is contained in:
Camilla Löwy 2019-05-20 17:13:09 +02:00
parent 051424f196
commit e01128f32f
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();
@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();

30
include/GLFW/glfw3.h
View File

@ -5069,23 +5069,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
@ -5096,23 +5099,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((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.
*
* @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