forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

better wording for time scaling docs (#6340)

Browse Source 
Quick follow-up to #5752. I think this is a slightly better wording.
This commit is contained in:
Cameron 2022-10-24 14:14:25 +00:00
parent c226fee707
commit 1d22634cfb
1 changed files with 44 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
crates/bevy_time/src/time.rs
View File

@ -2,16 +2,18 @@ use bevy_ecs::{reflect::ReflectResource, system::Resource};
use bevy_reflect::{FromReflect, Reflect};
use bevy_utils::{Duration, Instant};
/// Tracks how much time has advanced (and also how much real time has elapsed) since
/// the previous app update and since the app was started.
/// A clock that tracks how much it has advanced (and how much real time has elapsed) since
/// its previous update and since its creation.
#[derive(Resource, Reflect, FromReflect, Debug, Clone)]
#[reflect(Resource)]
pub struct Time {
startup: Instant,
first_update: Option<Instant>,
last_update: Option<Instant>,
relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
// pausing
paused: bool,
// scaling
relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
delta: Duration,
delta_seconds: f32,
delta_seconds_f64: f64,
@ -40,8 +42,8 @@ impl Default for Time {
startup: Instant::now(),
first_update: None,
last_update: None,
relative_speed: 1.0,
paused: false,
relative_speed: 1.0,
delta: Duration::ZERO,
delta_seconds: 0.0,
delta_seconds_f64: 0.0,
@ -142,7 +144,7 @@ impl Time {
} else if self.relative_speed != 1.0 {
raw_delta.mul_f64(self.relative_speed)
} else {
// avoid rounding errors at normal speed
// avoid rounding when at normal speed
raw_delta
};
@ -174,19 +176,25 @@ impl Time {
self.last_update = Some(instant);
}
/// Returns the [`Instant`] the app was started.
/// Returns the [`Instant`] the clock was created.
///
/// This usually represents when the app was started.
#[inline]
pub fn startup(&self) -> Instant {
self.startup
}
/// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists.
///
/// This usually represents when the first app update started.
#[inline]
pub fn first_update(&self) -> Option<Instant> {
self.first_update
}
/// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists.
///
/// This usually represents when the current app update started.
#[inline]
pub fn last_update(&self) -> Option<Instant> {
self.last_update
@ -256,31 +264,31 @@ impl Time {
self.elapsed_seconds_wrapped_f64
}
/// Returns the exact clock time elapsed since the last [`update`](#method.update), as a [`Duration`].
/// Returns how much real time has elapsed since the last [`update`](#method.update), as a [`Duration`].
#[inline]
pub fn raw_delta(&self) -> Duration {
self.raw_delta
}
/// Returns the exact clock time elapsed since the last [`update`](#method.update), as [`f32`] seconds.
/// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f32`] seconds.
#[inline]
pub fn raw_delta_seconds(&self) -> f32 {
self.raw_delta_seconds
}
/// Returns the exact clock time elapsed since the last [`update`](#method.update), as [`f64`] seconds.
/// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f64`] seconds.
#[inline]
pub fn raw_delta_seconds_f64(&self) -> f64 {
self.raw_delta_seconds_f64
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup), as [`Duration`].
/// Returns how much real time has elapsed since [`startup`](#method.startup), as [`Duration`].
#[inline]
pub fn raw_elapsed(&self) -> Duration {
self.raw_elapsed
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup), as [`f32`] seconds.
/// Returns how much real time has elapsed since [`startup`](#method.startup), as [`f32`] seconds.
///
/// **Note:** This is a monotonically increasing value. It's precision will degrade over time.
/// If you need an `f32` but that precision loss is unacceptable,
@ -290,20 +298,20 @@ impl Time {
self.raw_elapsed_seconds
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup), as [`f64`] seconds.
/// Returns how much real time has elapsed since [`startup`](#method.startup), as [`f64`] seconds.
#[inline]
pub fn raw_elapsed_seconds_f64(&self) -> f64 {
self.raw_elapsed_seconds_f64
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup) modulo
/// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
/// the [`wrap_period`](#method.wrap_period), as [`Duration`].
#[inline]
pub fn raw_elapsed_wrapped(&self) -> Duration {
self.raw_elapsed_wrapped
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup) modulo
/// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
/// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
///
/// This method is intended for applications (e.g. shaders) that require an [`f32`] value but
@ -313,7 +321,7 @@ impl Time {
self.raw_elapsed_seconds_wrapped
}
/// Returns the exact clock time elapsed since [`startup`](#method.startup) modulo
/// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
/// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
#[inline]
pub fn raw_elapsed_seconds_wrapped_f64(&self) -> f64 {
@ -332,17 +340,19 @@ impl Time {
/// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
/// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
///
/// **Note:** This will not take effect until the next update.
///
/// # Panics
///
/// Panics if `wrap_period` is zero.
/// Panics if `wrap_period` is a zero-length duration.
#[inline]
pub fn set_wrap_period(&mut self, wrap_period: Duration) {
assert!(wrap_period != Duration::ZERO, "division by zero");
assert!(!wrap_period.is_zero(), "division by zero");
self.wrap_period = wrap_period;
}
/// Returns the rate that time advances relative to real time, as [`f32`].
/// You might recognize this as "time scaling" or "time dilation" in other engines.
/// Returns the speed the clock advances relative to your system clock, as [`f32`].
/// This is known as "time scaling" or "time dilation" in other engines.
///
/// **Note:** This function will return zero when time is paused.
#[inline]
@ -350,8 +360,8 @@ impl Time {
self.relative_speed_f64() as f32
}
/// Returns the rate that time advances relative to real time, as [`f64`].
/// You might recognize this as "time scaling" or "time dilation" in other engines.
/// Returns the speed the clock advances relative to your system clock, as [`f64`].
/// This is known as "time scaling" or "time dilation" in other engines.
///
/// **Note:** This function will return zero when time is paused.
#[inline]
@ -363,9 +373,11 @@ impl Time {
}
}
/// Sets the rate that time advances relative to real time, given as an [`f32`].
/// Sets the speed the clock advances relative to your system clock, given as an [`f32`].
///
/// For example, if set to `2.0`, time will advance twice as fast as your system clock.
/// For example, setting this to `2.0` will make the clock advance twice as fast as your system clock.
///
/// **Note:** This does not affect the `raw_*` measurements.
///
/// # Panics
///
@ -375,9 +387,11 @@ impl Time {
self.set_relative_speed_f64(ratio as f64);
}
/// Sets the rate that time advances relative to real time, given as an [`f64`].
/// Sets the speed the clock advances relative to your system clock, given as an [`f64`].
///
/// For example, if set to `2.0`, time will advance twice as fast as your system clock.
/// For example, setting this to `2.0` will make the clock advance twice as fast as your system clock.
///
/// **Note:** This does not affect the `raw_*` measurements.
///
/// # Panics
///
@ -389,19 +403,21 @@ impl Time {
self.relative_speed = ratio;
}
/// Stops time, preventing it from advancing until resumed. Does not affect raw measurements.
/// Stops the clock, preventing it from advancing until resumed.
///
/// **Note:** This does affect the `raw_*` measurements.
#[inline]
pub fn pause(&mut self) {
self.paused = true;
}
/// Resumes time if paused.
/// Resumes the clock if paused.
#[inline]
pub fn unpause(&mut self) {
self.paused = false;
}
/// Returns `true` if time has been paused.
/// Returns `true` if the clock is currently paused.
#[inline]
pub fn is_paused(&self) -> bool {
self.paused