From 15b23b4e4aefc4a2570cd03fb7c80eac4c74a80b Mon Sep 17 00:00:00 2001 From: Justace Clutter Date: Tue, 5 May 2026 23:35:37 -0400 Subject: [PATCH] Add a warning for the use of Viewport with Window targets (#21830) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Objective This PR adds a warning in the Viewport portion of the Camera class to highlight the need to scale to physical pixels. This PR fixes #21828 ## Solution Adds a warning block in the class documentation ## Testing I build the documentation and it renders to the following: Camrea_Viewport_Warning --------- Co-authored-by: Alice Cecile Co-authored-by: ickshonpe Co-authored-by: François Mockers Co-authored-by: Carter Anderson --- crates/bevy_camera/src/camera.rs | 33 ++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/crates/bevy_camera/src/camera.rs b/crates/bevy_camera/src/camera.rs index c693880ffa..9714caf5a1 100644 --- a/crates/bevy_camera/src/camera.rs +++ b/crates/bevy_camera/src/camera.rs @@ -24,6 +24,39 @@ use wgpu_types::{BlendState, TextureUsages}; /// The viewport defines the area on the render target to which the camera renders its image. /// You can overlay multiple cameras in a single window using viewports to create effects like /// split screen, minimaps, and character viewers. +/// +///
+/// +/// Note that the physical position is in actual screen coordinates and not virtual pixels for window targets. +/// You should use the scaling factor reported by the window, which on some OS's defaults to a value other than 1. +/// Please see the example code (which assumes a single camera and window) +/// +/// ```no_run +/// # use bevy_camera::{Camera, Projection, Viewport}; +/// # use bevy_transform::prelude::Transform; +/// # use bevy_ecs::prelude::*; +/// # use bevy_math::UVec2; +/// # use bevy_window::Window; +/// # use bevy_utils::default; +/// +/// fn update_viewport( +/// mut camera_query: Query<(&mut Camera, &mut Transform, &mut Projection)>, +/// windows: Query<&Window> +/// ) { +/// let Ok((mut camera, _, _)) = camera_query.single_mut() else { return; }; +/// +/// let window = windows.single().expect("Window not found"); +/// let scale = window.resolution.scale_factor(); +/// +/// camera.viewport = Some(Viewport { +/// physical_position: (UVec2::new(10, 10).as_vec2() * scale).as_uvec2(), +/// physical_size: (UVec2::new(100, 100).as_vec2() * scale).as_uvec2(), +/// ..default() +/// }); +/// } +/// ``` +/// +///
#[derive(Reflect, Debug, Clone)] #[reflect(Default, Clone)] pub struct Viewport {