Add safe area and document coordinate systems (#3890)

Added `Window::safe_area`, which describes the area of the surface that
is unobstructed by notches, bezels etc. The drawing code in the examples
have been updated to draw a star inside the safe area, and the plain
background outside of it.

Also renamed `Window::inner_position` to `Window::surface_position`, and
changed it to from screen coordinates to window coordinates, to better
align how these coordinate systems work together.

Finally, added some SVG images and documentation to describe how all of
this works.

This is fully implemented on macOS and iOS, and partially on the web.

Co-authored-by: daxpedda <daxpedda@gmail.com>

src/platform_impl/web/event_loop/runner.rs

@@ -20,7 +20,7 @@ use crate::dpi::PhysicalSize;
 use crate::event::{DeviceEvent, ElementState, Event, RawKeyEvent, StartCause, WindowEvent};
 use crate::event_loop::{ControlFlow, DeviceEvents};
 use crate::platform::web::{PollStrategy, WaitUntilStrategy};
-use crate::platform_impl::platform::backend::EventListenerHandle;
+use crate::platform_impl::platform::backend::{EventListenerHandle, SafeAreaHandle};
 use crate::platform_impl::platform::r#async::DispatchRunner;
 use crate::platform_impl::platform::window::Inner;
 use crate::window::WindowId;
@@ -57,6 +57,7 @@ struct Execution {
     redraw_pending: RefCell<HashSet<WindowId>>,
     destroy_pending: RefCell<VecDeque<WindowId>>,
     pub(crate) monitor: Rc<MonitorHandler>,
+    safe_area: Rc<SafeAreaHandle>,
     page_transition_event_handle: RefCell<Option<backend::PageTransitionEventHandle>>,
     device_events: Cell<DeviceEvents>,
     on_mouse_move: OnEventHandle<PointerEvent>,
@@ -151,6 +152,8 @@ impl Shared {
                 WeakShared(weak.clone()),
             );
 
+            let safe_area = SafeAreaHandle::new(&window, &document);
+
             Execution {
                 main_thread,
                 event_loop_proxy: Arc::new(proxy_spawner),
@@ -170,6 +173,7 @@ impl Shared {
                 redraw_pending: RefCell::new(HashSet::new()),
                 destroy_pending: RefCell::new(VecDeque::new()),
                 monitor: Rc::new(monitor),
+                safe_area: Rc::new(safe_area),
                 page_transition_event_handle: RefCell::new(None),
                 device_events: Cell::default(),
                 on_mouse_move: RefCell::new(None),
@@ -826,6 +830,10 @@ impl Shared {
     pub(crate) fn monitor(&self) -> &Rc<MonitorHandler> {
         &self.0.monitor
     }
+
+    pub(crate) fn safe_area(&self) -> &Rc<SafeAreaHandle> {
+        &self.0.safe_area
+    }
 }
 
 #[derive(Clone, Debug)]

src/platform_impl/web/web_sys/canvas.rs

@@ -72,8 +72,8 @@ pub struct Common {
 
 #[derive(Clone, Debug)]
 pub struct Style {
-    read: CssStyleDeclaration,
-    write: CssStyleDeclaration,
+    pub(super) read: CssStyleDeclaration,
+    pub(super) write: CssStyleDeclaration,
 }
 
 impl Canvas {

src/platform_impl/web/web_sys/mod.rs

@@ -7,6 +7,7 @@ mod intersection_handle;
 mod media_query_handle;
 mod pointer;
 mod resize_scaling;
+mod safe_area;
 mod schedule;
 
 use std::cell::OnceCell;
@@ -20,6 +21,7 @@ use web_sys::{Document, HtmlCanvasElement, Navigator, PageTransitionEvent, Visib
 pub use self::canvas::{Canvas, Style};
 pub use self::event_handle::EventListenerHandle;
 pub use self::resize_scaling::ResizeScaleHandle;
+pub use self::safe_area::SafeAreaHandle;
 pub use self::schedule::Schedule;
 use crate::dpi::{LogicalPosition, LogicalSize};
 

src/platform_impl/web/web_sys/safe_area.rs

@@ -0,0 +1,56 @@
+use dpi::{LogicalPosition, LogicalSize};
+use wasm_bindgen::JsCast;
+use web_sys::{Document, HtmlHtmlElement, Window};
+
+use super::Style;
+
+pub struct SafeAreaHandle {
+    style: Style,
+}
+
+impl SafeAreaHandle {
+    pub fn new(window: &Window, document: &Document) -> Self {
+        let document: HtmlHtmlElement = document.document_element().unwrap().unchecked_into();
+        #[allow(clippy::disallowed_methods)]
+        let write = document.style();
+        write
+            .set_property(
+                "--__winit_safe_area",
+                "env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) \
+                 env(safe-area-inset-left)",
+            )
+            .expect("unexpected read-only declaration block");
+        #[allow(clippy::disallowed_methods)]
+        let read = window
+            .get_computed_style(&document)
+            .expect("failed to obtain computed style")
+            // this can't fail: we aren't using a pseudo-element
+            .expect("invalid pseudo-element");
+
+        SafeAreaHandle { style: Style { read, write } }
+    }
+
+    pub fn get(&self) -> (LogicalPosition<f64>, LogicalSize<f64>) {
+        let value = self.style.get("--__winit_safe_area");
+
+        let mut values = value
+            .split(' ')
+            .map(|value| value.strip_suffix("px").expect("unexpected unit other then `px` found"));
+        let top: f64 = values.next().unwrap().parse().unwrap();
+        let right: f64 = values.next().unwrap().parse().unwrap();
+        let bottom: f64 = values.next().unwrap().parse().unwrap();
+        let left: f64 = values.next().unwrap().parse().unwrap();
+        assert_eq!(values.next(), None, "unexpected fifth value");
+
+        let width = super::style_size_property(&self.style, "width") - left - right;
+        let height = super::style_size_property(&self.style, "height") - top - bottom;
+
+        (LogicalPosition::new(left, top), LogicalSize::new(width, height))
+    }
+}
+
+impl Drop for SafeAreaHandle {
+    fn drop(&mut self) {
+        self.style.remove("--__winit_safe_area");
+    }
+}

src/platform_impl/web/window.rs

@@ -2,13 +2,14 @@ use std::cell::Ref;
 use std::rc::Rc;
 use std::sync::Arc;
 
+use dpi::{LogicalPosition, LogicalSize};
 use web_sys::HtmlCanvasElement;
 
 use super::main_thread::{MainThreadMarker, MainThreadSafe};
 use super::monitor::MonitorHandler;
 use super::r#async::Dispatcher;
 use super::{backend, lock, ActiveEventLoop};
-use crate::dpi::{PhysicalPosition, PhysicalSize, Position, Size};
+use crate::dpi::{LogicalInsets, PhysicalInsets, PhysicalPosition, PhysicalSize, Position, Size};
 use crate::error::{NotSupportedError, RequestError};
 use crate::icon::Icon;
 use crate::monitor::MonitorHandle as RootMonitorHandle;
@@ -26,6 +27,7 @@ pub struct Inner {
     id: WindowId,
     pub window: web_sys::Window,
     monitor: Rc<MonitorHandler>,
+    safe_area: Rc<backend::SafeAreaHandle>,
     canvas: Rc<backend::Canvas>,
     destroy_fn: Option<Box<dyn FnOnce()>>,
 }
@@ -59,6 +61,7 @@ impl Window {
             id,
             window: window.clone(),
             monitor: Rc::clone(target.runner.monitor()),
+            safe_area: Rc::clone(target.runner.safe_area()),
             canvas,
             destroy_fn: Some(destroy_fn),
         };
@@ -109,9 +112,9 @@ impl RootWindow for Window {
         // Not supported
     }
 
-    fn inner_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
-        // Note: the canvas element has no window decorations, so this is equal to `outer_position`.
-        self.outer_position()
+    fn surface_position(&self) -> PhysicalPosition<i32> {
+        // Note: the canvas element has no window decorations.
+        (0, 0).into()
     }
 
     fn outer_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
@@ -152,6 +155,34 @@ impl RootWindow for Window {
         self.surface_size()
     }
 
+    fn safe_area(&self) -> PhysicalInsets<u32> {
+        self.inner.queue(|inner| {
+            let (safe_start_pos, safe_size) = inner.safe_area.get();
+            let safe_end_pos = LogicalPosition::new(
+                safe_start_pos.x + safe_size.width,
+                safe_start_pos.y + safe_size.height,
+            );
+
+            let surface_start_pos = inner.canvas.position();
+            let surface_size = LogicalSize::new(
+                backend::style_size_property(inner.canvas.style(), "width"),
+                backend::style_size_property(inner.canvas.style(), "height"),
+            );
+            let surface_end_pos = LogicalPosition::new(
+                surface_start_pos.x + surface_size.width,
+                surface_start_pos.y + surface_size.height,
+            );
+
+            let top = f64::max(safe_start_pos.y - surface_start_pos.y, 0.);
+            let left = f64::max(safe_start_pos.x - surface_start_pos.x, 0.);
+            let bottom = f64::max(surface_end_pos.y - safe_end_pos.y, 0.);
+            let right = f64::max(surface_end_pos.x - safe_end_pos.x, 0.);
+
+            let insets = LogicalInsets::new(top, left, bottom, right);
+            insets.to_physical(inner.scale_factor())
+        })
+    }
+
     fn set_min_surface_size(&self, min_size: Option<Size>) {
         self.inner.dispatch(move |inner| {
             let dimensions = min_size.map(|min_size| min_size.to_logical(inner.scale_factor()));