Rename camera "priority" to "order" (#6908)

# Objective
The documentation for camera priority is very confusing at the moment, it requires a bit of "double negative" kind of thinking.

# Solution
Flipping the wording on the documentation to reflect more common usecases like having an overlay camera and also renaming it to "order", since priority implies that it will override the other camera rather than have both run.

Author: Aceeri

crates/bevy_render/src/camera/camera.rs

@@ -86,8 +86,8 @@ pub struct ComputedCameraValues {
 pub struct Camera {
     /// If set, this camera will render to the given [`Viewport`] rectangle within the configured [`RenderTarget`].
     pub viewport: Option<Viewport>,
-    /// Cameras with a lower priority will be rendered before cameras with a higher priority.
-    pub priority: isize,
+    /// Cameras with a higher order are rendered later, and thus on top of lower order cameras.
+    pub order: isize,
     /// If this is set to `true`, this camera will be rendered to its specified [`RenderTarget`]. If `false`, this
     /// camera will not be rendered.
     pub is_active: bool,
@@ -109,7 +109,7 @@ impl Default for Camera {
     fn default() -> Self {
         Self {
             is_active: true,
-            priority: 0,
+            order: 0,
             viewport: None,
             computed: Default::default(),
             target: Default::default(),
@@ -477,7 +477,7 @@ pub struct ExtractedCamera {
     pub physical_target_size: Option<UVec2>,
     pub viewport: Option<Viewport>,
     pub render_graph: Cow<'static, str>,
-    pub priority: isize,
+    pub order: isize,
 }
 
 pub fn extract_cameras(
@@ -511,7 +511,7 @@ pub fn extract_cameras(
                     physical_viewport_size: Some(viewport_size),
                     physical_target_size: Some(target_size),
                     render_graph: camera_render_graph.0.clone(),
-                    priority: camera.priority,
+                    order: camera.order,
                 },
                 ExtractedView {
                     projection: camera.projection_matrix(),

crates/bevy_render/src/camera/camera_driver_node.rs

@@ -33,24 +33,24 @@ impl Node for CameraDriverNode {
         let mut sorted_cameras = self
             .cameras
             .iter_manual(world)
-            .map(|(e, c)| (e, c.priority, c.target.clone()))
+            .map(|(e, c)| (e, c.order, c.target.clone()))
             .collect::<Vec<_>>();
-        // sort by priority and ensure within a priority, RenderTargets of the same type are packed together
+        // sort by order and ensure within an order, RenderTargets of the same type are packed together
         sorted_cameras.sort_by(|(_, p1, t1), (_, p2, t2)| match p1.cmp(p2) {
             std::cmp::Ordering::Equal => t1.cmp(t2),
             ord => ord,
         });
         let mut camera_windows = HashSet::new();
-        let mut previous_priority_target = None;
+        let mut previous_order_target = None;
         let mut ambiguities = HashSet::new();
-        for (entity, priority, target) in sorted_cameras {
-            let new_priority_target = (priority, target);
-            if let Some(previous_priority_target) = previous_priority_target {
-                if previous_priority_target == new_priority_target {
-                    ambiguities.insert(new_priority_target.clone());
+        for (entity, order, target) in sorted_cameras {
+            let new_order_target = (order, target);
+            if let Some(previous_order_target) = previous_order_target {
+                if previous_order_target == new_order_target {
+                    ambiguities.insert(new_order_target.clone());
                 }
             }
-            previous_priority_target = Some(new_priority_target);
+            previous_order_target = Some(new_order_target);
             if let Ok((_, camera)) = self.cameras.get_manual(world, entity) {
                 if let RenderTarget::Window(id) = camera.target {
                     camera_windows.insert(id);
@@ -62,8 +62,8 @@ impl Node for CameraDriverNode {
 
         if !ambiguities.is_empty() {
             warn!(
-                "Camera priority ambiguities detected for active cameras with the following priorities: {:?}. \
-                To fix this, ensure there is exactly one Camera entity spawned with a given priority for a given RenderTarget. \
+                "Camera order ambiguities detected for active cameras with the following priorities: {:?}. \
+                To fix this, ensure there is exactly one Camera entity spawned with a given order for a given RenderTarget. \
                 Ambiguities should be resolved because either (1) multiple active cameras were spawned accidentally, which will \
                 result in rendering multiple instances of the scene or (2) for cases where multiple active cameras is intentional, \
                 ambiguities could result in unpredictable render results.",

examples/3d/render_to_texture.rs

@@ -102,7 +102,7 @@ fn setup(
             },
             camera: Camera {
                 // render before the "main pass" camera
-                priority: -1,
+                order: -1,
                 target: RenderTarget::Image(image_handle.clone()),
                 ..default()
             },

examples/3d/split_screen.rs

@@ -61,7 +61,7 @@ fn setup(
             transform: Transform::from_xyz(100.0, 100., 150.0).looking_at(Vec3::ZERO, Vec3::Y),
             camera: Camera {
                 // Renders the right camera after the left camera, which has a default priority of 0
-                priority: 1,
+                order: 1,
                 ..default()
             },
             camera_3d: Camera3d {

examples/3d/two_passes.rs

@@ -53,7 +53,7 @@ fn setup(
         },
         camera: Camera {
             // renders after / on top of the main camera
-            priority: 1,
+            order: 1,
             ..default()
         },
         ..default()

examples/shader/post_processing.rs

@@ -146,7 +146,7 @@ fn setup(
         Camera2dBundle {
             camera: Camera {
                 // renders after the first main camera which has default value: 0.
-                priority: 1,
+                order: 1,
                 ..default()
             },
             ..Camera2dBundle::default()

tests/window/minimising.rs

@@ -68,7 +68,7 @@ fn setup_2d(mut commands: Commands) {
     commands.spawn(Camera2dBundle {
         camera: Camera {
             // render the 2d camera after the 3d camera
-            priority: 1,
+            order: 1,
             ..default()
         },
         camera_2d: Camera2d {

tests/window/resizing.rs

@@ -148,7 +148,7 @@ fn setup_2d(mut commands: Commands) {
     commands.spawn(Camera2dBundle {
         camera: Camera {
             // render the 2d camera after the 3d camera
-            priority: 1,
+            order: 1,
             ..default()
         },
         camera_2d: Camera2d {