Add example demonstrating how to zoom orthographic cameras

[alice-i-cecile]

How can Bevy's documentation be improved?

Zooming an orthographic camera is surprisingly tricky; unlike ordinary cameras moving them further away from the object doesn't cause the size of the objects displayed to change as all their projection is parallel.

@TheRawMeatball provided this initial solution in #help:

fn zoom_system(
    mut whl: EventReader<MouseWheel>,
    mut cam: Query<(&mut Transform, &mut OrthographicProjection), With<MainCamera>>,
    windows: Res<Windows>,
) {
    let delta_zoom: f32 = whl.iter().map(|e| e.y).sum();
    if delta_zoom == 0. {
        return;
    }

    let (mut pos, mut cam) = cam.single_mut().unwrap();

    let window = windows.get_primary().unwrap();
    let window_size = Vec2::new(window.width(), window.height());
    let mouse_normalized_screen_pos =
        (window.cursor_position().unwrap() / window_size) * 2. - Vec2::ONE;
    let mouse_world_pos = pos.translation.truncate()
        + mouse_normalized_screen_pos * Vec2::new(cam.right, cam.top) * cam.scale;

    cam.scale -= ZOOM_SPEED * delta_zoom * cam.scale;
    cam.scale = cam.scale.clamp(MIN_ZOOM, MAX_ZOOM);

    pos.translation = (mouse_world_pos
        - mouse_normalized_screen_pos * Vec2::new(cam.right, cam.top) * cam.scale)
        .extend(pos.translation.z);
}

This should be straightforward to verify and clean up. Adding panning or rotation might also be worth including in the same example.

[Matthew-Maclean]

I think this should also note that if the scale is less than one then you may have to modify the far component on the projection, as per #239.

[BlackPhlox]

@alice-i-cecile I also think zoom for PerspectiveProjection (3D View) might be good for consistency.
Here's the PerspectiveProjection version (Based on my bevy_config_cam implementation)

fn zoom_3d_system(
    mut whl: EventReader<MouseWheel>,
    mut query: Query<(&mut Camera, &mut PerspectiveProjection)>,
	windows: Res<Windows>,
){
    let delta_zoom: f32 = whl.iter().map(|e| e.y).sum();
    if delta_zoom == 0. {
        return;
    }

    let prim = windows.get_primary().unwrap();
    for (mut camera, mut project) in query.iter_mut() {
        project.fov = (project.fov - delta_zoom * 0.01).abs();
        
        //Calculate projection with new fov
        project.update(prim.width(), prim.height());

        //Update camera with the new fov
        camera.projection_matrix = project.get_projection_matrix();
        camera.depth_calculation = project.depth_calculation();

        println!("FOV: {:?}", project.fov);
    }
}

[richchurcher]

I might take a crack at this one. I'm aware of related PR #11022 and will adopt that if the author doesn't clear the conflicts.

[richchurcher]

Hrm. Quite a bit has changed in OrthographicProjection since this issue's sample code was written. We now have area, for example. I'll see what I can come up with.

[richchurcher]

I notice that in 2024 I'm able to happily scroll without needing to modify the transform at all, take into account mouse position etc. Am I missing something? For example, this seems to work fine:

fn camera_controls(
    mut camera: Query<&mut Projection, With<Camera>>,
    mut mouse_wheel_input: EventReader<MouseWheel>,
) {
    let delta_zoom: f32 = mouse_wheel_input.read().map(|e| e.y).sum();
    if delta_zoom == 0. {
        return;
    }

    let mut projection = camera.single_mut();
    if let Projection::Orthographic(cam) = &mut *projection {
        let ScalingMode::FixedVertical(current) = cam.scaling_mode else {
            return;
        };
        let zoom_level = (current + CAMERA_ZOOM_SPEED * delta_zoom)
            .clamp(CAMERA_ZOOM_RANGE.start, CAMERA_ZOOM_RANGE.end);
        cam.scaling_mode = ScalingMode::FixedVertical(zoom_level);
    }
}

[richchurcher]

Quick demo: https://youtu.be/OVUyaQ0a8Ss

[richchurcher]

If we didn't need to clamp, we could just

cam.scaling_mode *= CAMERA_ZOOM_SPEED * delta_zoom;

and be done with it.