Merge branch 'main' into depth-prepass

CONTRIBUTING.md

@@ -76,37 +76,66 @@ Check out our dedicated [Bevy Organization document](/docs/the_bevy_organization
 
 ### Classifying PRs
 
-Our merge strategy relies on the classification of PRs into three categories: **trivial**, **uncontroversial** and **controversial**.
-When making PRs, try to split out more controversial changes from less controversial ones, in order to make your work easier to review and merge.
-PRs that are deemed controversial will receive the [`S-Controversial`](https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AS-Controversial) label, and will have to go through the more thorough review process.
+Our merge strategy relies on the classification of PRs on two axes:
 
-PRs are trivial if there is no reasonable argument against them. This might include:
+* How controversial are the design decisions
+* How complex is the implementation
 
-* Fixing dead links.
-* Removing dead code or dependencies.
-* Typo and grammar fixes.
+PRs with non-trivial design decisions are given the [`S-Controversial`] label. This indicates that
+the PR needs more thorough design review or an [RFC](https://github.com/bevyengine/rfcs), if complex enough.
 
-PRs are controversial if there is serious design discussion required, or a large impact to contributors or users. Factors that increase controversy include:
+PRs that are non-trivial to review are given the [`D-Complex`] label. This indicates that the PR
+should be reviewed more thoroughly and by people with experience in the area that the PR touches.
+
+When making PRs, try to split out more controversial changes from less controversial ones, in order to make your work easier to review and merge.
+It is also a good idea to try and split out simple changes from more complex changes if it is not helpful for then to be reviewed together.
 
-1. Changes to project-wide workflow or style.
+Some things that are reason to apply the [`S-Controversial`] label to a PR:
+
+1. Changes to a project-wide workflow or style.
 2. New architecture for a large feature.
-3. PRs where a serious tradeoff must be made.
+3. Serious tradeoffs were made.
 4. Heavy user impact.
 5. New ways for users to make mistakes (footguns).
-6. Introductions of `unsafe` code.
-7. Large-scale code reorganization.
-8. High levels of technical complexity.
-9. Adding a dependency.
-10. Touching licensing information (due to the level of precision required).
-11. Adding root-level files (due to the high level of visibility).
+6. Adding a dependency
+7. Touching licensing information (due to level of precision required).
+8. Adding root-level files (due to the high level of visibility)
+
+Some things that are reason to apply the [`D-Complex`] label to a PR:
+
+1. Introduction or modification of soundness relevent code (for example `unsafe` code)
+2. High levels of technical complexity.
+3. Large-scale code reorganization
+
+Examples of PRs that are not [`S-Controversial`] or [`D-Complex`]:
+
+* Fixing dead links.
+* Removing dead code or unused dependencies.
+* Typo and grammar fixes.
+* [Add `Mut::reborrow`](https://github.com/bevyengine/bevy/pull/7114)
+* [Add `Res::clone`](https://github.com/bevyengine/bevy/pull/4109)
+
+Examples of PRs that are [`S-Controversial`] but not [`D-Complex`]:
+
+* [Implement and require `#[derive(Component)]` on all component structs](https://github.com/bevyengine/bevy/pull/2254)
+* [Use default serde impls for Entity](https://github.com/bevyengine/bevy/pull/6194)
+
+Examples of PRs that are not [`S-Controversial`] but are [`D-Complex`]:
+
+* [Ensure `Ptr`/`PtrMut`/`OwningPtr` are aligned in debug builds](https://github.com/bevyengine/bevy/pull/7117)
+* [Replace `BlobVec`'s `swap_scratch` with a `swap_nonoverlapping`](https://github.com/bevyengine/bevy/pull/4853)
+
+Examples of PRs that are both [`S-Controversial`] and [`D-Complex`]:
+
+* [bevy_reflect: Binary formats](https://github.com/bevyengine/bevy/pull/6140)
 
-Finally, changes are "relatively uncontroversial" if they are neither trivial or controversial.
-Most PRs should fall into this category.
+Some useful pull request queries:
 
-Here are some useful pull request queries:
+* [PRs which need reviews and are not `D-Complex`](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+-label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked++)
+* [`D-Complex` PRs which need reviews](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked)
 
-* [Uncontroversial pull requests which have been reviewed and are ready for maintainers to merge](https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AS-Ready-For-Final-Review+-label%3AS-Controversial+-label%3AS-Blocked+-label%3AS-Adopt-Me+)
-* [Controversial pull requests which have been reviewed and are ready for final input from a Project Lead or SME](https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AS-Ready-For-Final-Review+label%3AS-Controversial+)
+[`S-Controversial`]: https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AS-Controversial
+[`D-Complex`]: https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AD-Complex
 
 ### Preparing Releases
 

Cargo.toml

@@ -763,6 +763,16 @@ description = "Shows how to load and play an audio file, and control how it's pl
 category = "Audio"
 wasm = true
 
+[[example]]
+name = "decodable"
+path = "examples/audio/decodable.rs"
+
+[package.metadata.example.decodable]
+name = "Decodable"
+description = "Shows how to create and register a custom audio source by implementing the `Decodable` type."
+category = "Audio"
+wasm = true
+
 # Diagnostics
 [[example]]
 name = "log_diagnostics"

crates/bevy_app/src/app.rs

@@ -178,6 +178,24 @@ impl App {
  /// Finalizes the [`App`] configuration. For general usage, see the example on the item
  /// level documentation.
  ///
+ /// # `run()` might not return
+ ///
+ /// Calls to [`App::run()`] might never return.
+ ///
+ /// In simple and *headless* applications, one can expect that execution will
+ /// proceed, normally, after calling [`run()`](App::run()) but this is not the case for
+ /// windowed applications.
+ ///
+ /// Windowed apps are typically driven by an *event loop* or *message loop* and
+ /// some window-manager APIs expect programs to terminate when their primary
+ /// window is closed and that event loop terminates – behaviour of processes that
+ /// do not is often platform dependent or undocumented.
+ ///
+ /// By default, *Bevy* uses the `winit` crate for window creation. See
+ /// [`WinitSettings::return_from_run`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run)
+ /// for further discussion of this topic and for a mechanism to require that [`App::run()`]
+ /// *does* return – albeit one that carries its own caveats and disclaimers.
+ ///
  /// # Panics
  ///
  /// Panics if called from `Plugin::build()`, because it would prevent other plugins to properly build.

crates/bevy_asset/src/assets.rs

@@ -417,7 +417,7 @@ macro_rules! load_internal_asset {
  let mut debug_app = $app
  .world
  .non_send_resource_mut::<$crate::debug_asset_server::DebugAssetApp>();
- $crate::debug_asset_server::register_handle_with_loader(
+ $crate::debug_asset_server::register_handle_with_loader::<_, &'static str>(
  $loader,
  &mut debug_app,
  $handle,
@@ -455,7 +455,7 @@ macro_rules! load_internal_binary_asset {
  let mut debug_app = $app
  .world
  .non_send_resource_mut::<$crate::debug_asset_server::DebugAssetApp>();
- $crate::debug_asset_server::register_handle_with_loader(
+ $crate::debug_asset_server::register_handle_with_loader::<_, &'static [u8]>(
  $loader,
  &mut debug_app,
  $handle,

crates/bevy_asset/src/debug_asset_server.rs

@@ -116,8 +116,8 @@ pub(crate) fn sync_debug_assets<T: Asset + Clone>(
 ///
 /// If this feels a bit odd ... that's because it is. This was built to improve the UX of the
 /// `load_internal_asset` macro.
-pub fn register_handle_with_loader<A: Asset>(
- _loader: fn(&'static str) -> A,
+pub fn register_handle_with_loader<A: Asset, T>(
+ _loader: fn(T) -> A,
  app: &mut DebugAssetApp,
  handle: HandleUntyped,
  file_path: &str,

crates/bevy_audio/src/audio_source.rs

@@ -1,5 +1,5 @@
 use anyhow::Result;
-use bevy_asset::{AssetLoader, LoadContext, LoadedAsset};
+use bevy_asset::{Asset, AssetLoader, LoadContext, LoadedAsset};
 use bevy_reflect::TypeUuid;
 use bevy_utils::BoxedFuture;
 use std::{io::Cursor, sync::Arc};
@@ -63,14 +63,24 @@ impl AssetLoader for AudioLoader {
  }
 }
 
-/// A type implementing this trait can be decoded as a rodio source
+/// A type implementing this trait can be converted to a [`rodio::Source`] type.
+/// It must be [`Send`] and [`Sync`], and usually implements [`Asset`] so needs to be [`TypeUuid`],
+/// in order to be registered.
+/// Types that implement this trait usually contain raw sound data that can be converted into an iterator of samples.
+/// This trait is implemented for [`AudioSource`].
+/// Check the example `audio/decodable` for how to implement this trait on a custom type.
 pub trait Decodable: Send + Sync + 'static {
- /// The decoder that can decode the implementing type
- type Decoder: rodio::Source + Send + Iterator<Item = Self::DecoderItem>;
- /// A single value given by the decoder
+ /// The type of the audio samples.
+ /// Usually a [`u16`], [`i16`] or [`f32`], as those implement [`rodio::Sample`].
+ /// Other types can implement the [`rodio::Sample`] trait as well.
  type DecoderItem: rodio::Sample + Send + Sync;
 
- /// Build and return a [`Self::Decoder`] for the implementing type
+ /// The type of the iterator of the audio samples,
+ /// which iterates over samples of type [`Self::DecoderItem`].
+ /// Must be a [`rodio::Source`] so that it can provide information on the audio it is iterating over.
+ type Decoder: rodio::Source + Send + Iterator<Item = Self::DecoderItem>;
+
+ /// Build and return a [`Self::Decoder`] of the implementing type
  fn decoder(&self) -> Self::Decoder;
 }
 
@@ -82,3 +92,17 @@ impl Decodable for AudioSource {
  rodio::Decoder::new(Cursor::new(self.clone())).unwrap()
  }
 }
+
+/// A trait that allows adding a custom audio source to the object.
+/// This is implemented for [`App`][bevy_app::App] to allow registering custom [`Decodable`] types.
+pub trait AddAudioSource {
+ /// Registers an audio source.
+ /// The type must implement [`Decodable`],
+ /// so that it can be converted to a [`rodio::Source`] type,
+ /// and [`Asset`], so that it can be registered as an asset.
+ /// To use this method on [`App`][bevy_app::App],
+ /// the [audio][super::AudioPlugin] and [asset][bevy_asset::AssetPlugin] plugins must be added first. 
+ fn add_audio_source<T>(&mut self) -> &mut Self
+ where
+ T: Decodable + Asset;
+}

crates/bevy_audio/src/lib.rs

@@ -35,12 +35,13 @@ pub mod prelude {
 pub use audio::*;
 pub use audio_output::*;
 pub use audio_source::*;
+
 pub use rodio::cpal::Sample as CpalSample;
 pub use rodio::source::Source;
 pub use rodio::Sample;
 
 use bevy_app::prelude::*;
-use bevy_asset::AddAsset;
+use bevy_asset::{AddAsset, Asset};
 
 /// Adds support for audio playback to a Bevy Application
 ///
@@ -63,3 +64,15 @@ impl Plugin for AudioPlugin {
  app.init_asset_loader::<AudioLoader>();
  }
 }
+
+impl AddAudioSource for App {
+ fn add_audio_source<T>(&mut self) -> &mut Self
+ where
+ T: Decodable + Asset,
+ {
+ self.add_asset::<T>()
+ .init_resource::<Audio<T>>()
+ .init_resource::<AudioOutput<T>>()
+ .add_system_to_stage(CoreStage::PostUpdate, play_queued_audio_system::<T>)
+ }
+}

crates/bevy_core_pipeline/src/bloom/bloom.wgsl

@@ -5,6 +5,7 @@ struct BloomUniforms {
  knee: f32,
  scale: f32,
  intensity: f32,
+ viewport: vec4<f32>,
 };
 
 @group(0) @binding(0)
@@ -87,7 +88,8 @@ fn sample_original_3x3_tent(uv: vec2<f32>, scale: vec2<f32>) -> vec4<f32> {
 }
 
 @fragment
-fn downsample_prefilter(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+fn downsample_prefilter(@location(0) output_uv: vec2<f32>) -> @location(0) vec4<f32> {
+ let sample_uv = uniforms.viewport.xy + output_uv * uniforms.viewport.zw;
  let texel_size = 1.0 / vec2<f32>(textureDimensions(original));
 
  let scale = texel_size;
@@ -98,7 +100,7 @@ fn downsample_prefilter(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
  0.25 / uniforms.knee,
  );
 
- var o: vec4<f32> = sample_13_tap(uv, scale);
+ var o: vec4<f32> = sample_13_tap(sample_uv, scale);
 
  o = quadratic_threshold(o, uniforms.threshold, curve);
  o = max(o, vec4<f32>(0.00001));

crates/bevy_core_pipeline/src/bloom/mod.rs

@@ -7,7 +7,7 @@ use bevy_ecs::{
  system::{Commands, Query, Res, ResMut, Resource},
  world::{FromWorld, World},
 };
-use bevy_math::UVec2;
+use bevy_math::{UVec2, UVec4, Vec4};
 use bevy_reflect::{Reflect, TypeUuid};
 use bevy_render::{
  camera::ExtractedCamera,
@@ -152,18 +152,27 @@ impl ExtractComponent for BloomSettings {
  return None;
  }
 
- camera.physical_viewport_size().map(|size| {
+ if let (Some((origin, _)), Some(size), Some(target_size)) = (
+ camera.physical_viewport_rect(),
+ camera.physical_viewport_size(),
+ camera.physical_target_size(),
+ ) {
  let min_view = size.x.min(size.y) / 2;
  let mip_count = calculate_mip_count(min_view);
  let scale = (min_view / 2u32.pow(mip_count)) as f32 / 8.0;
 
- BloomUniform {
+ Some(BloomUniform {
  threshold: settings.threshold,
  knee: settings.knee,
  scale: settings.scale * scale,
  intensity: settings.intensity,
- }
- })
+ viewport: UVec4::new(origin.x, origin.y, size.x, size.y).as_vec4()
+ / UVec4::new(target_size.x, target_size.y, target_size.x, target_size.y)
+ .as_vec4(),
+ })
+ } else {
+ None
+ }
  }
 }
 
@@ -246,9 +255,6 @@ impl Node for BloomNode {
  &bind_groups.prefilter_bind_group,
  &[uniform_index.index()],
  );
- if let Some(viewport) = camera.viewport.as_ref() {
- prefilter_pass.set_camera_viewport(viewport);
- }
  prefilter_pass.draw(0..3, 0..1);
  }
 
@@ -270,9 +276,6 @@ impl Node for BloomNode {
  &bind_groups.downsampling_bind_groups[mip as usize - 1],
  &[uniform_index.index()],
  );
- if let Some(viewport) = camera.viewport.as_ref() {
- downsampling_pass.set_camera_viewport(viewport);
- }
  downsampling_pass.draw(0..3, 0..1);
  }
 
@@ -294,9 +297,6 @@ impl Node for BloomNode {
  &bind_groups.upsampling_bind_groups[mip as usize - 1],
  &[uniform_index.index()],
  );
- if let Some(viewport) = camera.viewport.as_ref() {
- upsampling_pass.set_camera_viewport(viewport);
- }
  upsampling_pass.draw(0..3, 0..1);
  }
 
@@ -612,6 +612,7 @@ pub struct BloomUniform {
  knee: f32,
  scale: f32,
  intensity: f32,
+ viewport: Vec4,
 }
 
 #[derive(Component)]

crates/bevy_ecs/macros/src/lib.rs

@@ -4,7 +4,9 @@ mod component;
 mod fetch;
 
 use crate::fetch::derive_world_query_impl;
-use bevy_macro_utils::{derive_label, get_named_struct_fields, BevyManifest};
+use bevy_macro_utils::{
+ derive_boxed_label, derive_label, derive_set, get_named_struct_fields, BevyManifest,
+};
 use proc_macro::TokenStream;
 use proc_macro2::Span;
 use quote::{format_ident, quote};
@@ -565,6 +567,32 @@ pub fn derive_run_criteria_label(input: TokenStream) -> TokenStream {
  derive_label(input, &trait_path, "run_criteria_label")
 }
 
+/// Derive macro generating an impl of the trait `ScheduleLabel`.
+#[proc_macro_derive(ScheduleLabel)]
+pub fn derive_schedule_label(input: TokenStream) -> TokenStream {
+ let input = parse_macro_input!(input as DeriveInput);
+ let mut trait_path = bevy_ecs_path();
+ trait_path
+ .segments
+ .push(format_ident!("schedule_v3").into());
+ trait_path
+ .segments
+ .push(format_ident!("ScheduleLabel").into());
+ derive_boxed_label(input, &trait_path)
+}
+
+/// Derive macro generating an impl of the trait `SystemSet`.
+#[proc_macro_derive(SystemSet)]
+pub fn derive_system_set(input: TokenStream) -> TokenStream {
+ let input = parse_macro_input!(input as DeriveInput);
+ let mut trait_path = bevy_ecs_path();
+ trait_path
+ .segments
+ .push(format_ident!("schedule_v3").into());
+ trait_path.segments.push(format_ident!("SystemSet").into());
+ derive_set(input, &trait_path)
+}
+
 pub(crate) fn bevy_ecs_path() -> syn::Path {
  BevyManifest::default().get_path("bevy_ecs")
 }