Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-22 20:53:53 +00:00
Code Issues Projects Releases Packages 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_reflect::{FromReflect, Reflect};
use bevy_utils::{Duration, Instant}; use bevy_utils::{Duration, Instant};
/// Tracks how much time has advanced (and also how much real time has elapsed) since /// A clock that tracks how much it has advanced (and how much real time has elapsed) since
/// the previous app update and since the app was started. /// its previous update and since its creation.
#[derive(Resource, Reflect, FromReflect, Debug, Clone)] #[derive(Resource, Reflect, FromReflect, Debug, Clone)]
#[reflect(Resource)] #[reflect(Resource)]
pub struct Time { pub struct Time {
startup: Instant, startup: Instant,
first_update: Option<Instant>, first_update: Option<Instant>,
last_update: Option<Instant>, last_update: Option<Instant>,
relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors // pausing
paused: bool, paused: bool,
// scaling
relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
delta: Duration, delta: Duration,
delta_seconds: f32, delta_seconds: f32,
delta_seconds_f64: f64, delta_seconds_f64: f64,
@ -40,8 +42,8 @@ impl Default for Time {
startup: Instant::now(), startup: Instant::now(),
first_update: None, first_update: None,
last_update: None, last_update: None,
relative_speed: 1.0,
paused: false, paused: false,
relative_speed: 1.0,
delta: Duration::ZERO, delta: Duration::ZERO,
delta_seconds: 0.0, delta_seconds: 0.0,
delta_seconds_f64: 0.0, delta_seconds_f64: 0.0,
@ -142,7 +144,7 @@ impl Time {
} else if self.relative_speed != 1.0 { } else if self.relative_speed != 1.0 {
raw_delta.mul_f64(self.relative_speed) raw_delta.mul_f64(self.relative_speed)
} else { } else {
// avoid rounding errors at normal speed // avoid rounding when at normal speed
raw_delta raw_delta
}; };
@ -174,19 +176,25 @@ impl Time {
self.last_update = Some(instant); 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] #[inline]
pub fn startup(&self) -> Instant { pub fn startup(&self) -> Instant {
self.startup self.startup
} }
/// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists. /// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists.
///
/// This usually represents when the first app update started.
#[inline] #[inline]
pub fn first_update(&self) -> Option<Instant> { pub fn first_update(&self) -> Option<Instant> {
self.first_update self.first_update
} }
/// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists. /// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists.
///
/// This usually represents when the current app update started.
#[inline] #[inline]
pub fn last_update(&self) -> Option<Instant> { pub fn last_update(&self) -> Option<Instant> {
self.last_update self.last_update
@ -256,31 +264,31 @@ impl Time {
self.elapsed_seconds_wrapped_f64 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] #[inline]
pub fn raw_delta(&self) -> Duration { pub fn raw_delta(&self) -> Duration {
self.raw_delta 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] #[inline]
pub fn raw_delta_seconds(&self) -> f32 { pub fn raw_delta_seconds(&self) -> f32 {
self.raw_delta_seconds 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] #[inline]
pub fn raw_delta_seconds_f64(&self) -> f64 { pub fn raw_delta_seconds_f64(&self) -> f64 {
self.raw_delta_seconds_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] #[inline]
pub fn raw_elapsed(&self) -> Duration { pub fn raw_elapsed(&self) -> Duration {
self.raw_elapsed 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. /// **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, /// If you need an `f32` but that precision loss is unacceptable,
@ -290,20 +298,20 @@ impl Time {
self.raw_elapsed_seconds 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] #[inline]
pub fn raw_elapsed_seconds_f64(&self) -> f64 { pub fn raw_elapsed_seconds_f64(&self) -> f64 {
self.raw_elapsed_seconds_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`]. /// the [`wrap_period`](#method.wrap_period), as [`Duration`].
#[inline] #[inline]
pub fn raw_elapsed_wrapped(&self) -> Duration { pub fn raw_elapsed_wrapped(&self) -> Duration {
self.raw_elapsed_wrapped 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. /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
/// ///
/// This method is intended for applications (e.g. shaders) that require an [`f32`] value but /// 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 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. /// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
#[inline] #[inline]
pub fn raw_elapsed_seconds_wrapped_f64(&self) -> f64 { 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 /// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
/// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped). /// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
/// ///
/// **Note:** This will not take effect until the next update.
///
/// # Panics /// # Panics
/// ///
/// Panics if `wrap_period` is zero. /// Panics if `wrap_period` is a zero-length duration.
#[inline] #[inline]
pub fn set_wrap_period(&mut self, wrap_period: Duration) { 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; self.wrap_period = wrap_period;
} }
/// Returns the rate that time advances relative to real time, as [`f32`]. /// Returns the speed the clock advances relative to your system clock, as [`f32`].
/// You might recognize this as "time scaling" or "time dilation" in other engines. /// This is known as "time scaling" or "time dilation" in other engines.
/// ///
/// **Note:** This function will return zero when time is paused. /// **Note:** This function will return zero when time is paused.
#[inline] #[inline]
@ -350,8 +360,8 @@ impl Time {
self.relative_speed_f64() as f32 self.relative_speed_f64() as f32
} }
/// Returns the rate that time advances relative to real time, as [`f64`]. /// Returns the speed the clock advances relative to your system clock, as [`f64`].
/// You might recognize this as "time scaling" or "time dilation" in other engines. /// This is known as "time scaling" or "time dilation" in other engines.
/// ///
/// **Note:** This function will return zero when time is paused. /// **Note:** This function will return zero when time is paused.
#[inline] #[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 /// # Panics
/// ///
@ -375,9 +387,11 @@ impl Time {
self.set_relative_speed_f64(ratio as f64); 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 /// # Panics
/// ///
@ -389,19 +403,21 @@ impl Time {
self.relative_speed = ratio; 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] #[inline]
pub fn pause(&mut self) { pub fn pause(&mut self) {
self.paused = true; self.paused = true;
} }
/// Resumes time if paused. /// Resumes the clock if paused.
#[inline] #[inline]
pub fn unpause(&mut self) { pub fn unpause(&mut self) {
self.paused = false; self.paused = false;
} }
/// Returns `true` if time has been paused. /// Returns `true` if the clock is currently paused.
#[inline] #[inline]
pub fn is_paused(&self) -> bool { pub fn is_paused(&self) -> bool {
self.paused self.paused