Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@maniwani
maniwani committed Mar 7, 2022
1 parent 399abde commit 8394e9b
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 51 deletions.
66 changes: 33 additions & 33 deletions crates/bevy_core/src/time/fixed_timestep.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ use bevy_utils::{Duration, Instant};

use crate::Time;

/// The default step size used for the fixed timestep.
/// The default step size used by [`FixedTimestep`].
// 60Hz is a popular tick rate, but it can't be expressed as an exact float.
// The nearby power of two, 64Hz, is more stable for numerical integration.
pub const DEFAULT_TIMESTEP: Duration = Duration::from_micros(15625); // 64Hz

/// `FixedTime` tracks how much time has advanced since its previous update and since the app was started.
/// Tracks how much time has advanced since its previous update and since the app was started.
///
/// It's just like [`Time`](super::time::Time) (and internally coupled to it), except it updates in fixed increments.
/// It's just like [`Time`] (and internally coupled to it), except it advances in fixed increments.
#[derive(Debug, Clone)]
pub struct FixedTime {
startup: Instant,
Expand Down Expand Up @@ -69,7 +69,7 @@ impl FixedTime {
self.update_with_instant(now);
}

/// Advances fixed time by the fixed delta and records the [`Instant`] it happened.
/// Advances time by [`FixedTime::delta`] and records the [`Instant`] it happened.
pub(crate) fn update_with_instant(&mut self, instant: Instant) {
if self.last_update.is_none() {
self.first_update = Some(instant);
Expand All @@ -86,40 +86,40 @@ impl FixedTime {
self.startup
}

/// Returns the [`Instant`] when [`FixedTime::update`] was first called, if it exists.
/// Returns the [`Instant`] when [`update`](FixedTime::update) was first called, if it exists.
#[inline]
pub fn first_update(&self) -> Option<Instant> {
self.first_update
}

/// Returns the [`Instant`] when [`FixedTime::update`] was last called, if it exists.
/// Returns the [`Instant`] when [`update`](FixedTime::update) was last called, if it exists.
#[inline]
pub fn last_update(&self) -> Option<Instant> {
self.last_update
}

/// Returns how much fixed time advances in each update, as a [`Duration`].
/// Returns how much time advances with each [`update`](FixedTime::update), as a [`Duration`].
#[inline]
pub fn delta(&self) -> Duration {
self.delta
}

/// Returns how much fixed time advances in each update, as [`f32`] seconds.
/// Returns how much time advances with each [`update`](FixedTime::update), as [`f32`] seconds.
#[inline]
pub fn delta_seconds(&self) -> f32 {
self.delta_seconds
}

/// Returns how much fixed time advances in each update, as [`f64`] seconds.
/// Returns how much time advances with each [`update`](FixedTime::update), as [`f64`] seconds.
#[inline]
pub fn delta_seconds_f64(&self) -> f64 {
self.delta_seconds_f64
}

/// Sets the timestep to `delta`, given as [`Duration`].
/// Sets the timestep te `delta`, given as [`Duration`].
///
/// Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will change system behavior.
/// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will likely change system behavior.
///
/// # Panics
///
Expand All @@ -131,46 +131,46 @@ impl FixedTime {
self.delta_seconds_f64 = self.delta.as_secs_f64();
}

/// Sets the timestep to `delta`, given as [`f32`].
/// Sets the timestep te `delta`, given as [`f32`].
///
/// Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will change system behavior.
/// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will likely change system behavior.
///
/// # Panics
///
/// Panics if `delta` is less than or equal to zero, not finite, or overflows the `Duration`.
/// Panics if `delta` is less than or equal to zero, not finite, or overflows a `Duration`.
pub fn set_delta_f32(&mut self, delta: f32) {
self.set_delta(Duration::from_secs_f32(delta));
}

/// Sets the timestep to `delta`, given as [`f64`].
/// Sets the timestep te `delta`, given as [`f64`].
///
/// Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will change system behavior.
/// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will likely change system behavior.
///
/// # Panics
///
/// Panics if `delta` is less than or equal to zero, not finite, or overflows the `Duration`.
/// Panics if `delta` is less than or equal to zero, not finite, or overflows a `Duration`.
pub fn set_delta_f64(&mut self, delta: f64) {
self.set_delta(Duration::from_secs_f64(delta));
}

/// Returns the nominal fixed update rate (reciprocal of [`FixedTime::delta`]) as [`f32`].
/// Returns the nominal update rate (reciprocal of [`FixedTime::delta`]) as [`f32`].
#[inline]
pub fn steps_per_second(&self) -> f32 {
1.0 / self.delta_seconds
}

/// Returns the nominal fixed update rate (reciprocal of [`FixedTime::delta`]) as [`f64`].
/// Returns the nominal update rate (reciprocal of [`FixedTime::delta`]) as [`f64`].
#[inline]
pub fn steps_per_second_f64(&self) -> f64 {
1.0 / self.delta_seconds_f64
}

/// Sets the timestep to the reciprocal of `rate`, given as [`f32`].
///
/// Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will change system behavior.
/// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will likely change system behavior.
///
/// # Panics
///
Expand All @@ -183,8 +183,8 @@ impl FixedTime {

/// Sets the timestep to the reciprocal of `rate`, given as [`f64`].
///
/// Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will change system behavior.
/// Note: Outside of startup, users should prefer using [`Time::set_relative_speed`]
/// as changing the timestep itself will likely change system behavior.
///
/// # Panics
///
Expand All @@ -195,26 +195,26 @@ impl FixedTime {
self.set_delta(Duration::from_secs_f64(1.0 / rate));
}

/// Returns how much fixed time has advanced since startup, as [`Duration`].
/// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`Duration`].
#[inline]
pub fn elapsed_since_startup(&self) -> Duration {
self.elapsed_since_startup
}

/// Returns how much fixed time has advanced since startup, as [`f32`] seconds.
/// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`f32`] seconds.
#[inline]
pub fn seconds_since_startup(&self) -> f32 {
self.seconds_since_startup
}

/// Returns how much fixed time has advanced since startup, as [`f64`] seconds.
/// Returns how much time has advanced since [`startup`](FixedTime::startup), as [`f64`] seconds.
#[inline]
pub fn seconds_since_startup_f64(&self) -> f64 {
self.seconds_since_startup_f64
}
}

/// Accumulates time and converts it into steps: one step per `timestep` accumulated. Used to drive [`FixedTime`].
/// Accumulates time and converts it into steps: one step per [`FixedTime::delta`] accumulated. Used to drive [`FixedTime`] and [`FixedTimestep`].
#[derive(Debug, Clone)]
pub struct FixedTimestepState {
steps: u32,
Expand Down Expand Up @@ -250,7 +250,7 @@ impl FixedTimestepState {

/// Returns the amount of time accumulated toward new steps, as an [`f32`] fraction of `timestep`.
///
/// Use this function when interpolating data between two timesteps.
/// Use this function when interpolating data between consecutive [`FixedTimestep`] iterations.
///
/// # Panics
///
Expand All @@ -262,7 +262,7 @@ impl FixedTimestepState {

/// Returns the amount of time accumulated toward new steps, as an [`f64`] fraction of `timestep`.
///
/// Use this function when interpolating data between two timesteps.
/// Use this function when interpolating data between consecutive [`FixedTimestep`] iterations.
///
/// # Panics
///
Expand All @@ -273,7 +273,7 @@ impl FixedTimestepState {
}

/// Adds `time` to the internal `overstep`, then converts the `overstep` accumulated into
/// as many steps of size `timestep` as possible.
/// as many `timestep`-sized steps as possible.
///
/// # Panics
///
Expand Down
36 changes: 18 additions & 18 deletions crates/bevy_core/src/time/time.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ use bevy_utils::{Duration, Instant};

use crate::{FixedTime, FixedTimestepState};

/// `Time` tracks how much time has advanced (and also the raw CPU time elapsed) since its previous update and since the app was started.
/// Tracks how much time has advanced (and also the raw CPU time elapsed) since its previous update and since the app was started.
#[derive(Debug, Clone)]
pub struct Time {
startup: Instant,
Expand Down Expand Up @@ -103,13 +103,13 @@ impl Time {
self.startup
}

/// Returns the [`Instant`] when [`Time::update`] was first called, if it exists.
/// Returns the [`Instant`] when [`update`](Time::update) was first called, if it exists.
#[inline]
pub fn first_update(&self) -> Option<Instant> {
self.first_update
}

/// Returns the [`Instant`] when [`Time::update`] was last called, if it exists.
/// Returns the [`Instant`] when [`update`](Time::update) was last called, if it exists.
#[inline]
pub fn last_update(&self) -> Option<Instant> {
self.last_update
Expand All @@ -135,7 +135,7 @@ impl Time {
///
/// # Panics
///
/// Panics if `ratio` negative or not finite.
/// Panics if `ratio` is negative or not finite.
pub fn set_relative_speed(&mut self, ratio: f32) {
assert!(ratio.is_finite(), "tried to go infinitely fast");
assert!(ratio.is_sign_positive(), "tried to go back in time");
Expand All @@ -146,87 +146,87 @@ impl Time {
///
/// # Panics
///
/// Panics if `ratio` negative or not finite.
/// Panics if `ratio` is negative or not finite.
pub fn set_relative_speed_f64(&mut self, ratio: f64) {
assert!(ratio.is_finite(), "tried to go infinitely fast");
assert!(ratio.is_sign_positive(), "tried to go back in time");
self.relative_speed = ratio;
}

/// Returns how much time has advanced since the last update, as a [`Duration`].
/// Returns how much time has advanced since the last [`update`](Time::update), as a [`Duration`].
#[inline]
pub fn delta(&self) -> Duration {
self.delta
}

/// Returns how much time has advanced since the last update, as [`f32`] seconds.
/// Returns how much time has advanced since the last [`update`](Time::update), as [`f32`] seconds.
#[inline]
pub fn delta_seconds(&self) -> f32 {
self.delta_seconds
}

/// Returns how much time has advanced since the last update, as [`f64`] seconds.
/// Returns how much time has advanced since the last [`update`](Time::update), as [`f64`] seconds.
#[inline]
pub fn delta_seconds_f64(&self) -> f64 {
self.delta_seconds_f64
}

/// Returns the exact CPU time elapsed since the last update, as a [`Duration`].
/// Returns the exact CPU time elapsed since the last [`update`](Time::update), as a [`Duration`].
#[inline]
pub fn raw_delta(&self) -> Duration {
self.raw_delta
}

/// Returns the exact CPU time elapsed since the last update, as [`f32`] seconds.
/// Returns the exact CPU time elapsed since the last [`update`](Time::update), as [`f32`] seconds.
#[inline]
pub fn raw_delta_seconds(&self) -> f32 {
self.raw_delta_seconds
}

/// Returns the exact CPU time elapsed since the last update, as [`f64`] seconds.
/// Returns the exact CPU time elapsed since the last [`update`](Time::update), as [`f64`] seconds.
#[inline]
pub fn raw_delta_seconds_f64(&self) -> f64 {
self.raw_delta_seconds_f64
}

/// Returns how much time has advanced since startup, as [`Duration`].
/// Returns how much time has advanced since [`startup`](Time::startup), as [`Duration`].
#[inline]
pub fn elapsed_since_startup(&self) -> Duration {
self.elapsed_since_startup
}

/// Returns how much time has advanced since startup, as [`f32`] seconds.
/// Returns how much time has advanced since [`startup`](Time::startup), as [`f32`] seconds.
#[inline]
pub fn seconds_since_startup(&self) -> f32 {
self.seconds_since_startup
}

/// Returns how much time has advanced since startup, as [`f64`] seconds.
/// Returns how much time has advanced since [`startup`](Time::startup), as [`f64`] seconds.
#[inline]
pub fn seconds_since_startup_f64(&self) -> f64 {
self.seconds_since_startup_f64
}

/// Returns the exact CPU time elapsed since startup, as [`Duration`].
/// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`Duration`].
#[inline]
pub fn raw_elapsed_since_startup(&self) -> Duration {
self.raw_elapsed_since_startup
}

/// Returns the exact CPU time elapsed since startup, as [`f32`] seconds.
/// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`f32`] seconds.
#[inline]
pub fn raw_seconds_since_startup(&self) -> f32 {
self.raw_seconds_since_startup
}

/// Returns the exact CPU time elapsed since startup, as [`f64`] seconds.
/// Returns the exact CPU time elapsed since [`startup`](Time::startup), as [`f64`] seconds.
#[inline]
pub fn raw_seconds_since_startup_f64(&self) -> f64 {
self.raw_seconds_since_startup_f64
}
}

/// Advances `Time` and accumulates the amount advanced for `FixedTime`.
/// Advances [`Time`] and accumulates the amount advanced for [`FixedTime`].
pub(crate) fn update_time(
mut time: ResMut<Time>,
fixed_time: Option<Res<FixedTime>>,
Expand Down

0 comments on commit 8394e9b

Please sign in to comment.