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.
This commit is contained in:
Aceeri 2022-12-25 00:39:30 +00:00
parent a0448eca2f
commit 8ad9a7c7c4
8 changed files with 22 additions and 22 deletions

View file

@ -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(),

View file

@ -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.",

View file

@ -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()
},

View file

@ -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 {

View file

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

View file

@ -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()

View file

@ -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 {

View file

@ -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 {