From 1d22634cfbef189ba7355f6114f418885b06da9b Mon Sep 17 00:00:00 2001 From: Cameron <51241057+maniwani@users.noreply.github.com> Date: Mon, 24 Oct 2022 14:14:25 +0000 Subject: [PATCH] better wording for time scaling docs (#6340) Quick follow-up to #5752. I think this is a slightly better wording. --- crates/bevy_time/src/time.rs | 72 ++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs index e6d2d70c9af82..d752bdd51de5b 100644 --- a/crates/bevy_time/src/time.rs +++ b/crates/bevy_time/src/time.rs @@ -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, last_update: Option, - 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 { 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 { 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, setting this to `2.0` will make the clock advance twice as fast as your system clock. /// - /// For example, if set to `2.0`, time will 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