bevy_render/
extract_param.rs

1use crate::MainWorld;
2use bevy_ecs::{
3    component::Tick,
4    prelude::*,
5    system::{ReadOnlySystemParam, SystemMeta, SystemParam, SystemParamItem, SystemState},
6    world::unsafe_world_cell::UnsafeWorldCell,
7};
8use core::ops::{Deref, DerefMut};
9
10/// A helper for accessing [`MainWorld`] content using a system parameter.
11///
12/// A [`SystemParam`] adapter which applies the contained `SystemParam` to the [`World`]
13/// contained in [`MainWorld`]. This parameter only works for systems run
14/// during the [`ExtractSchedule`](crate::ExtractSchedule).
15///
16/// This requires that the contained [`SystemParam`] does not mutate the world, as it
17/// uses a read-only reference to [`MainWorld`] internally.
18///
19/// ## Context
20///
21/// [`ExtractSchedule`] is used to extract (move) data from the simulation world ([`MainWorld`]) to the
22/// render world. The render world drives rendering each frame (generally to a `Window`).
23/// This design is used to allow performing calculations related to rendering a prior frame at the same
24/// time as the next frame is simulated, which increases throughput (FPS).
25///
26/// [`Extract`] is used to get data from the main world during [`ExtractSchedule`].
27///
28/// ## Examples
29///
30/// ```
31/// use bevy_ecs::prelude::*;
32/// use bevy_render::Extract;
33/// use bevy_render::sync_world::RenderEntity;
34/// # #[derive(Component)]
35/// // Do make sure to sync the cloud entities before extracting them.
36/// # struct Cloud;
37/// fn extract_clouds(mut commands: Commands, clouds: Extract<Query<RenderEntity, With<Cloud>>>) {
38///     for cloud in &clouds {
39///         commands.entity(cloud).insert(Cloud);
40///     }
41/// }
42/// ```
43///
44/// [`ExtractSchedule`]: crate::ExtractSchedule
45/// [Window]: bevy_window::Window
46pub struct Extract<'w, 's, P>
47where
48    P: ReadOnlySystemParam + 'static,
49{
50    item: SystemParamItem<'w, 's, P>,
51}
52
53#[doc(hidden)]
54pub struct ExtractState<P: SystemParam + 'static> {
55    state: SystemState<P>,
56    main_world_state: <Res<'static, MainWorld> as SystemParam>::State,
57}
58
59// SAFETY: The only `World` access (`Res<MainWorld>`) is read-only.
60unsafe impl<P> ReadOnlySystemParam for Extract<'_, '_, P> where P: ReadOnlySystemParam {}
61
62// SAFETY: The only `World` access is properly registered by `Res<MainWorld>::init_state`.
63// This call will also ensure that there are no conflicts with prior params.
64unsafe impl<P> SystemParam for Extract<'_, '_, P>
65where
66    P: ReadOnlySystemParam,
67{
68    type State = ExtractState<P>;
69    type Item<'w, 's> = Extract<'w, 's, P>;
70
71    fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State {
72        let mut main_world = world.resource_mut::<MainWorld>();
73        ExtractState {
74            state: SystemState::new(&mut main_world),
75            main_world_state: Res::<MainWorld>::init_state(world, system_meta),
76        }
77    }
78
79    #[inline]
80    unsafe fn validate_param(
81        state: &Self::State,
82        system_meta: &SystemMeta,
83        world: UnsafeWorldCell,
84    ) -> bool {
85        // SAFETY: Read-only access to world data registered in `init_state`.
86        let result = unsafe { world.get_resource_by_id(state.main_world_state) };
87        let Some(main_world) = result else {
88            system_meta.try_warn_param::<&World>();
89            return false;
90        };
91        // SAFETY: Type is guaranteed by `SystemState`.
92        let main_world: &World = unsafe { main_world.deref() };
93        // SAFETY: We provide the main world on which this system state was initialized on.
94        unsafe {
95            SystemState::<P>::validate_param(
96                &state.state,
97                main_world.as_unsafe_world_cell_readonly(),
98            )
99        }
100    }
101
102    #[inline]
103    unsafe fn get_param<'w, 's>(
104        state: &'s mut Self::State,
105        system_meta: &SystemMeta,
106        world: UnsafeWorldCell<'w>,
107        change_tick: Tick,
108    ) -> Self::Item<'w, 's> {
109        // SAFETY:
110        // - The caller ensures that `world` is the same one that `init_state` was called with.
111        // - The caller ensures that no other `SystemParam`s will conflict with the accesses we have registered.
112        let main_world = unsafe {
113            Res::<MainWorld>::get_param(
114                &mut state.main_world_state,
115                system_meta,
116                world,
117                change_tick,
118            )
119        };
120        let item = state.state.get(main_world.into_inner());
121        Extract { item }
122    }
123}
124
125impl<'w, 's, P> Deref for Extract<'w, 's, P>
126where
127    P: ReadOnlySystemParam,
128{
129    type Target = SystemParamItem<'w, 's, P>;
130
131    #[inline]
132    fn deref(&self) -> &Self::Target {
133        &self.item
134    }
135}
136
137impl<'w, 's, P> DerefMut for Extract<'w, 's, P>
138where
139    P: ReadOnlySystemParam,
140{
141    #[inline]
142    fn deref_mut(&mut self) -> &mut Self::Target {
143        &mut self.item
144    }
145}
146
147impl<'a, 'w, 's, P> IntoIterator for &'a Extract<'w, 's, P>
148where
149    P: ReadOnlySystemParam,
150    &'a SystemParamItem<'w, 's, P>: IntoIterator,
151{
152    type Item = <&'a SystemParamItem<'w, 's, P> as IntoIterator>::Item;
153    type IntoIter = <&'a SystemParamItem<'w, 's, P> as IntoIterator>::IntoIter;
154
155    fn into_iter(self) -> Self::IntoIter {
156        (&self.item).into_iter()
157    }
158}
bevy_render/extract_param.rs

bevy_render/
extract_param.rs
