mirror of
https://github.com/bevyengine/bevy
synced 2024-11-25 14:10:19 +00:00
Improved documentation for Events (#1669)
Explains subtle behavior more explicitly, documents `add_event`, mentions `EventWriter`. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
This commit is contained in:
parent
5fedb6029a
commit
ab0165d20d
5 changed files with 39 additions and 12 deletions
|
@ -207,6 +207,10 @@ impl AppBuilder {
|
|||
.add_stage(CoreStage::Last, SystemStage::parallel())
|
||||
}
|
||||
|
||||
/// Setup the application to manage events of type `T`.
|
||||
///
|
||||
/// This is done by adding a `Resource` of type `Events::<T>`,
|
||||
/// and inserting a `Events::<T>::update_system` system into `CoreStage::First`.
|
||||
pub fn add_event<T>(&mut self) -> &mut Self
|
||||
where
|
||||
T: Component,
|
||||
|
|
|
@ -56,11 +56,23 @@ enum State {
|
|||
}
|
||||
|
||||
/// An event collection that represents the events that occurred within the last two
|
||||
/// [Events::update] calls. Events can be cheaply read using an [EventReader]. This collection is
|
||||
/// meant to be paired with a system that calls [Events::update] exactly once per update/frame.
|
||||
/// [Events::update_system] is a system that does this. [EventReader]s are expected to read events
|
||||
/// from this collection at least once per update/frame. If events are not handled within one
|
||||
/// frame/update, they will be dropped.
|
||||
/// [`Events::update`] calls.
|
||||
/// Events can be written to using an [`EventWriter`]
|
||||
/// and are typically cheaply read using an [`EventReader`].
|
||||
///
|
||||
/// Each event can be consumed by multiple systems, in parallel,
|
||||
/// with consumption tracked by the [`EventReader`] on a per-system basis.
|
||||
///
|
||||
/// This collection is meant to be paired with a system that calls
|
||||
/// [`Events::update`] exactly once per update/frame.
|
||||
///
|
||||
/// [`Events::update_system`] is a system that does this, typically intialized automatically using
|
||||
/// [`AppBuilder::add_event`]. [EventReader]s are expected to read events from this collection at
|
||||
/// least once per loop/frame.
|
||||
/// Events will persist across a single frame boundary and so ordering of event producers and
|
||||
/// consumers is not critical (although poorly-planned ordering may cause accumulating lag).
|
||||
/// If events are not handled by the end of the frame after they are updated, they will be
|
||||
/// dropped silently.
|
||||
///
|
||||
/// # Example
|
||||
/// ```
|
||||
|
@ -100,7 +112,9 @@ enum State {
|
|||
/// The buffers in [Events] will grow indefinitely if [Events::update] is never called.
|
||||
///
|
||||
/// An alternative call pattern would be to call [Events::update] manually across frames to control
|
||||
/// when events are cleared. However this complicates consumption
|
||||
/// when events are cleared.
|
||||
/// This complicates consumption and risks ever-expanding memory usage if not cleaned up,
|
||||
/// but can be done by adding your event as a resource instead of using [`AppBuilder::add_event`].
|
||||
#[derive(Debug)]
|
||||
pub struct Events<T> {
|
||||
events_a: Vec<EventInstance<T>>,
|
||||
|
|
|
@ -173,18 +173,21 @@ impl SystemStage {
|
|||
pub fn parallel_systems(&self) -> &[impl SystemContainer] {
|
||||
&self.parallel
|
||||
}
|
||||
|
||||
/// Topologically sorted exclusive systems that want to be run at the start of the stage.
|
||||
///
|
||||
/// Note that systems won't be fully-formed until the stage has been run at least once.
|
||||
pub fn exclusive_at_start_systems(&self) -> &[impl SystemContainer] {
|
||||
&self.exclusive_at_start
|
||||
}
|
||||
|
||||
/// Topologically sorted exclusive systems that want to be run at the end of the stage.
|
||||
///
|
||||
/// Note that systems won't be fully-formed until the stage has been run at least once.
|
||||
pub fn exclusive_at_end_systems(&self) -> &[impl SystemContainer] {
|
||||
&self.exclusive_at_end
|
||||
}
|
||||
|
||||
/// Topologically sorted exclusive systems that want to be run after parallel systems but
|
||||
/// before the application of their command buffers.
|
||||
///
|
||||
|
|
|
@ -188,7 +188,8 @@ impl<T: Component + Clone + Eq> State<T> {
|
|||
|
||||
/// Creates a driver set for the State.
|
||||
///
|
||||
/// Important note: this set must be inserted **before** all other state-dependant sets to work properly!
|
||||
/// Important note: this set must be inserted **before** all other state-dependant sets to work
|
||||
/// properly!
|
||||
pub fn make_driver() -> SystemSet {
|
||||
SystemSet::default().with_run_criteria(state_cleaner::<T>.system())
|
||||
}
|
||||
|
@ -203,7 +204,8 @@ impl<T: Component + Clone + Eq> State<T> {
|
|||
}
|
||||
|
||||
/// Schedule a state change that replaces the full stack with the given state.
|
||||
/// This will fail if there is a scheduled operation, or if the given `state` matches the current state
|
||||
/// This will fail if there is a scheduled operation, or if the given `state` matches the
|
||||
/// current state
|
||||
pub fn set_next(&mut self, state: T) -> Result<(), StateError> {
|
||||
if self.stack.last().unwrap() == &state {
|
||||
return Err(StateError::AlreadyInState);
|
||||
|
@ -217,7 +219,8 @@ impl<T: Component + Clone + Eq> State<T> {
|
|||
Ok(())
|
||||
}
|
||||
|
||||
/// Same as [Self::set_next], but if there is already a next state, it will be overwritten instead of failing
|
||||
/// Same as [Self::set_next], but if there is already a next state, it will be overwritten
|
||||
/// instead of failing
|
||||
pub fn overwrite_next(&mut self, state: T) -> Result<(), StateError> {
|
||||
if self.stack.last().unwrap() == &state {
|
||||
return Err(StateError::AlreadyInState);
|
||||
|
@ -241,7 +244,8 @@ impl<T: Component + Clone + Eq> State<T> {
|
|||
Ok(())
|
||||
}
|
||||
|
||||
/// Same as [Self::set_push], but if there is already a next state, it will be overwritten instead of failing
|
||||
/// Same as [Self::set_push], but if there is already a next state, it will be overwritten
|
||||
/// instead of failing
|
||||
pub fn overwrite_push(&mut self, state: T) -> Result<(), StateError> {
|
||||
if self.stack.last().unwrap() == &state {
|
||||
return Err(StateError::AlreadyInState);
|
||||
|
@ -265,7 +269,8 @@ impl<T: Component + Clone + Eq> State<T> {
|
|||
Ok(())
|
||||
}
|
||||
|
||||
/// Same as [Self::set_pop], but if there is already a next state, it will be overwritten instead of failing
|
||||
/// Same as [Self::set_pop], but if there is already a next state, it will be overwritten
|
||||
/// instead of failing
|
||||
pub fn overwrite_pop(&mut self) -> Result<(), StateError> {
|
||||
if self.stack.len() == 1 {
|
||||
return Err(StateError::StackEmpty);
|
||||
|
|
|
@ -58,7 +58,8 @@ pub enum StorageTextureAccess {
|
|||
/// ```
|
||||
WriteOnly,
|
||||
/// The texture can be both read and written in the shader.
|
||||
/// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access mode.
|
||||
/// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access
|
||||
/// mode.
|
||||
///
|
||||
/// Example GLSL syntax:
|
||||
/// ```cpp,ignore
|
||||
|
|
Loading…
Reference in a new issue