Make `RenderStage::Extract` run on the render world (#4402)
# Objective
- Currently, the `Extract` `RenderStage` is executed on the main world, with the render world available as a resource.
- However, when needing access to resources in the render world (e.g. to mutate them), the only way to do so was to get exclusive access to the whole `RenderWorld` resource.
- This meant that effectively only one extract which wrote to resources could run at a time.
- We didn't previously make `Extract`ing writing to the world a non-happy path, even though we want to discourage that.
## Solution
- Move the extract stage to run on the render world.
- Add the main world as a `MainWorld` resource.
- Add an `Extract` `SystemParam` as a convenience to access a (read only) `SystemParam` in the main world during `Extract`.
## Future work
It should be possible to avoid needing to use `get_or_spawn` for the render commands, since now the `Commands`' `Entities` matches up with the world being executed on.
We need to determine how this interacts with https://github.com/bevyengine/bevy/pull/3519
It's theoretically possible to remove the need for the `value` method on `Extract`. However, that requires slightly changing the `SystemParam` interface, which would make it more complicated. That would probably mess up the `SystemState` api too.
## Todo
I still need to add doc comments to `Extract`.
---
## Changelog
### Changed
- The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase.
Resources on the render world can now be accessed using `ResMut` during extract.
### Removed
- `Commands::spawn_and_forget`. Use `Commands::get_or_spawn(e).insert_bundle(bundle)` instead
## Migration Guide
The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase. `Extract` takes a single type parameter, which is any system parameter (such as `Res`, `Query` etc.). It will extract this from the main world, and returns the result of this extraction when `value` is called on it.
For example, if previously your extract system looked like:
```rust
fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
for cloud in clouds.iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
the new version would be:
```rust
fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
The diff is:
```diff
--- a/src/clouds.rs
+++ b/src/clouds.rs
@@ -1,5 +1,5 @@
-fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
- for cloud in clouds.iter() {
+fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
+ for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
You can now also access resources from the render world using the normal system parameters during `Extract`:
```rust
fn extract_assets(mut render_assets: ResMut<MyAssets>, source_assets: Extract<Res<MyAssets>>) {
*render_assets = source_assets.clone();
}
```
Please note that all existing extract systems need to be updated to match this new style; even if they currently compile they will not run as expected. A warning will be emitted on a best-effort basis if this is not met.
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-08 23:56:33 +00:00
|
|
|
use crate::MainWorld;
|
|
|
|
use bevy_ecs::{
|
|
|
|
prelude::*,
|
|
|
|
system::{
|
|
|
|
ReadOnlySystemParamFetch, ResState, SystemMeta, SystemParam, SystemParamFetch,
|
2022-09-20 00:29:10 +00:00
|
|
|
SystemParamItem, SystemParamState, SystemState,
|
Make `RenderStage::Extract` run on the render world (#4402)
# Objective
- Currently, the `Extract` `RenderStage` is executed on the main world, with the render world available as a resource.
- However, when needing access to resources in the render world (e.g. to mutate them), the only way to do so was to get exclusive access to the whole `RenderWorld` resource.
- This meant that effectively only one extract which wrote to resources could run at a time.
- We didn't previously make `Extract`ing writing to the world a non-happy path, even though we want to discourage that.
## Solution
- Move the extract stage to run on the render world.
- Add the main world as a `MainWorld` resource.
- Add an `Extract` `SystemParam` as a convenience to access a (read only) `SystemParam` in the main world during `Extract`.
## Future work
It should be possible to avoid needing to use `get_or_spawn` for the render commands, since now the `Commands`' `Entities` matches up with the world being executed on.
We need to determine how this interacts with https://github.com/bevyengine/bevy/pull/3519
It's theoretically possible to remove the need for the `value` method on `Extract`. However, that requires slightly changing the `SystemParam` interface, which would make it more complicated. That would probably mess up the `SystemState` api too.
## Todo
I still need to add doc comments to `Extract`.
---
## Changelog
### Changed
- The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase.
Resources on the render world can now be accessed using `ResMut` during extract.
### Removed
- `Commands::spawn_and_forget`. Use `Commands::get_or_spawn(e).insert_bundle(bundle)` instead
## Migration Guide
The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase. `Extract` takes a single type parameter, which is any system parameter (such as `Res`, `Query` etc.). It will extract this from the main world, and returns the result of this extraction when `value` is called on it.
For example, if previously your extract system looked like:
```rust
fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
for cloud in clouds.iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
the new version would be:
```rust
fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
The diff is:
```diff
--- a/src/clouds.rs
+++ b/src/clouds.rs
@@ -1,5 +1,5 @@
-fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
- for cloud in clouds.iter() {
+fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
+ for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
You can now also access resources from the render world using the normal system parameters during `Extract`:
```rust
fn extract_assets(mut render_assets: ResMut<MyAssets>, source_assets: Extract<Res<MyAssets>>) {
*render_assets = source_assets.clone();
}
```
Please note that all existing extract systems need to be updated to match this new style; even if they currently compile they will not run as expected. A warning will be emitted on a best-effort basis if this is not met.
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-08 23:56:33 +00:00
|
|
|
},
|
|
|
|
};
|
|
|
|
use std::ops::{Deref, DerefMut};
|
|
|
|
|
|
|
|
/// A helper for accessing [`MainWorld`] content using a system parameter.
|
|
|
|
///
|
|
|
|
/// A [`SystemParam`] adapter which applies the contained `SystemParam` to the [`World`]
|
|
|
|
/// contained in [`MainWorld`]. This parameter only works for systems run
|
|
|
|
/// during [`RenderStage::Extract`].
|
|
|
|
///
|
|
|
|
/// This requires that the contained [`SystemParam`] does not mutate the world, as it
|
|
|
|
/// uses a read-only reference to [`MainWorld`] internally.
|
|
|
|
///
|
|
|
|
/// ## Context
|
|
|
|
///
|
|
|
|
/// [`RenderStage::Extract`] is used to extract (move) data from the simulation world ([`MainWorld`]) to the
|
|
|
|
/// render world. The render world drives rendering each frame (generally to a [Window]).
|
|
|
|
/// This design is used to allow performing calculations related to rendering a prior frame at the same
|
|
|
|
/// time as the next frame is simulated, which increases throughput (FPS).
|
|
|
|
///
|
|
|
|
/// [`Extract`] is used to get data from the main world during [`RenderStage::Extract`].
|
|
|
|
///
|
|
|
|
/// ## Examples
|
|
|
|
///
|
|
|
|
/// ```rust
|
|
|
|
/// use bevy_ecs::prelude::*;
|
|
|
|
/// use bevy_render::Extract;
|
|
|
|
/// # #[derive(Component)]
|
|
|
|
/// # struct Cloud;
|
|
|
|
/// fn extract_clouds(mut commands: Commands, clouds: Extract<Query<Entity, With<Cloud>>>) {
|
2022-09-20 00:29:10 +00:00
|
|
|
/// for cloud in &clouds {
|
Make `RenderStage::Extract` run on the render world (#4402)
# Objective
- Currently, the `Extract` `RenderStage` is executed on the main world, with the render world available as a resource.
- However, when needing access to resources in the render world (e.g. to mutate them), the only way to do so was to get exclusive access to the whole `RenderWorld` resource.
- This meant that effectively only one extract which wrote to resources could run at a time.
- We didn't previously make `Extract`ing writing to the world a non-happy path, even though we want to discourage that.
## Solution
- Move the extract stage to run on the render world.
- Add the main world as a `MainWorld` resource.
- Add an `Extract` `SystemParam` as a convenience to access a (read only) `SystemParam` in the main world during `Extract`.
## Future work
It should be possible to avoid needing to use `get_or_spawn` for the render commands, since now the `Commands`' `Entities` matches up with the world being executed on.
We need to determine how this interacts with https://github.com/bevyengine/bevy/pull/3519
It's theoretically possible to remove the need for the `value` method on `Extract`. However, that requires slightly changing the `SystemParam` interface, which would make it more complicated. That would probably mess up the `SystemState` api too.
## Todo
I still need to add doc comments to `Extract`.
---
## Changelog
### Changed
- The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase.
Resources on the render world can now be accessed using `ResMut` during extract.
### Removed
- `Commands::spawn_and_forget`. Use `Commands::get_or_spawn(e).insert_bundle(bundle)` instead
## Migration Guide
The `Extract` `RenderStage` now runs on the render world (instead of the main world as before).
You must use the `Extract` `SystemParam` to access the main world during the extract phase. `Extract` takes a single type parameter, which is any system parameter (such as `Res`, `Query` etc.). It will extract this from the main world, and returns the result of this extraction when `value` is called on it.
For example, if previously your extract system looked like:
```rust
fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
for cloud in clouds.iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
the new version would be:
```rust
fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
The diff is:
```diff
--- a/src/clouds.rs
+++ b/src/clouds.rs
@@ -1,5 +1,5 @@
-fn extract_clouds(mut commands: Commands, clouds: Query<Entity, With<Cloud>>) {
- for cloud in clouds.iter() {
+fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
+ for cloud in clouds.value().iter() {
commands.get_or_spawn(cloud).insert(Cloud);
}
}
```
You can now also access resources from the render world using the normal system parameters during `Extract`:
```rust
fn extract_assets(mut render_assets: ResMut<MyAssets>, source_assets: Extract<Res<MyAssets>>) {
*render_assets = source_assets.clone();
}
```
Please note that all existing extract systems need to be updated to match this new style; even if they currently compile they will not run as expected. A warning will be emitted on a best-effort basis if this is not met.
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-08 23:56:33 +00:00
|
|
|
/// commands.get_or_spawn(cloud).insert(Cloud);
|
|
|
|
/// }
|
|
|
|
/// }
|
|
|
|
/// ```
|
|
|
|
///
|
|
|
|
/// [`RenderStage::Extract`]: crate::RenderStage::Extract
|
|
|
|
/// [Window]: bevy_window::Window
|
|
|
|
pub struct Extract<'w, 's, P: SystemParam + 'static>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
{
|
|
|
|
item: <P::Fetch as SystemParamFetch<'w, 's>>::Item,
|
|
|
|
}
|
|
|
|
|
|
|
|
impl<'w, 's, P: SystemParam> SystemParam for Extract<'w, 's, P>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
{
|
|
|
|
type Fetch = ExtractState<P>;
|
|
|
|
}
|
|
|
|
|
|
|
|
#[doc(hidden)]
|
|
|
|
pub struct ExtractState<P: SystemParam> {
|
|
|
|
state: SystemState<P>,
|
|
|
|
main_world_state: ResState<MainWorld>,
|
|
|
|
}
|
|
|
|
|
|
|
|
// SAFETY: only accesses MainWorld resource with read only system params using ResState,
|
|
|
|
// which is initialized in init()
|
|
|
|
unsafe impl<P: SystemParam + 'static> SystemParamState for ExtractState<P> {
|
|
|
|
fn init(world: &mut World, system_meta: &mut SystemMeta) -> Self {
|
|
|
|
let mut main_world = world.resource_mut::<MainWorld>();
|
|
|
|
Self {
|
|
|
|
state: SystemState::new(&mut main_world),
|
|
|
|
main_world_state: ResState::init(world, system_meta),
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl<'w, 's, P: SystemParam + 'static> SystemParamFetch<'w, 's> for ExtractState<P>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
{
|
|
|
|
type Item = Extract<'w, 's, P>;
|
|
|
|
|
|
|
|
unsafe fn get_param(
|
|
|
|
state: &'s mut Self,
|
|
|
|
system_meta: &SystemMeta,
|
|
|
|
world: &'w World,
|
|
|
|
change_tick: u32,
|
|
|
|
) -> Self::Item {
|
|
|
|
let main_world = ResState::<MainWorld>::get_param(
|
|
|
|
&mut state.main_world_state,
|
|
|
|
system_meta,
|
|
|
|
world,
|
|
|
|
change_tick,
|
|
|
|
);
|
|
|
|
let item = state.state.get(main_world.into_inner());
|
|
|
|
Extract { item }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl<'w, 's, P: SystemParam> Deref for Extract<'w, 's, P>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
{
|
|
|
|
type Target = <P::Fetch as SystemParamFetch<'w, 's>>::Item;
|
|
|
|
|
|
|
|
#[inline]
|
|
|
|
fn deref(&self) -> &Self::Target {
|
|
|
|
&self.item
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl<'w, 's, P: SystemParam> DerefMut for Extract<'w, 's, P>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
{
|
|
|
|
#[inline]
|
|
|
|
fn deref_mut(&mut self) -> &mut Self::Target {
|
|
|
|
&mut self.item
|
|
|
|
}
|
|
|
|
}
|
2022-09-20 00:29:10 +00:00
|
|
|
|
|
|
|
impl<'a, 'w, 's, P: SystemParam> IntoIterator for &'a Extract<'w, 's, P>
|
|
|
|
where
|
|
|
|
P::Fetch: ReadOnlySystemParamFetch,
|
|
|
|
&'a SystemParamItem<'w, 's, P>: IntoIterator,
|
|
|
|
{
|
|
|
|
type Item = <&'a SystemParamItem<'w, 's, P> as IntoIterator>::Item;
|
|
|
|
type IntoIter = <&'a SystemParamItem<'w, 's, P> as IntoIterator>::IntoIter;
|
|
|
|
|
|
|
|
fn into_iter(self) -> Self::IntoIter {
|
|
|
|
(&self.item).into_iter()
|
|
|
|
}
|
|
|
|
}
|