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/linux/wayland/window/mod.rs

@@ -17,7 +17,7 @@ use super::output::MonitorHandle;
 use super::state::WinitState;
 use super::types::xdg_activation::XdgActivationTokenData;
 use super::ActiveEventLoop;
-use crate::dpi::{LogicalSize, PhysicalPosition, PhysicalSize, Position, Size};
+use crate::dpi::{LogicalSize, PhysicalInsets, PhysicalPosition, PhysicalSize, Position, Size};
 use crate::error::{NotSupportedError, RequestError};
 use crate::event::{Ime, WindowEvent};
 use crate::event_loop::AsyncRequestSerial;
@@ -303,9 +303,8 @@ impl CoreWindow for Window {
         crate::platform_impl::common::xkb::reset_dead_keys()
     }
 
-    fn inner_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
-        Err(NotSupportedError::new("window position information is not available on Wayland")
-            .into())
+    fn surface_position(&self) -> PhysicalPosition<i32> {
+        (0, 0).into()
     }
 
     fn outer_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
@@ -336,6 +335,10 @@ impl CoreWindow for Window {
         super::logical_to_physical_rounded(window_state.outer_size(), scale_factor)
     }
 
+    fn safe_area(&self) -> PhysicalInsets<u32> {
+        PhysicalInsets::new(0, 0, 0, 0)
+    }
+
     fn set_min_surface_size(&self, min_size: Option<Size>) {
         let scale_factor = self.scale_factor();
         let min_size = min_size.map(|size| size.to_logical(scale_factor));

src/platform_impl/linux/x11/util/geometry.rs

@@ -67,15 +67,20 @@ pub struct FrameExtentsHeuristic {
 }
 
 impl FrameExtentsHeuristic {
-    pub fn inner_pos_to_outer(&self, x: i32, y: i32) -> (i32, i32) {
+    pub fn surface_position(&self) -> (i32, i32) {
         use self::FrameExtentsHeuristicPath::*;
         if self.heuristic_path != UnsupportedBordered {
-            (x - self.frame_extents.left as i32, y - self.frame_extents.top as i32)
+            (self.frame_extents.left as i32, self.frame_extents.top as i32)
         } else {
-            (x, y)
+            (0, 0)
         }
     }
 
+    pub fn inner_pos_to_outer(&self, x: i32, y: i32) -> (i32, i32) {
+        let (left, top) = self.surface_position();
+        (x - left, y - top)
+    }
+
     pub fn surface_size_to_outer(&self, width: u32, height: u32) -> (u32, u32) {
         (
             width.saturating_add(

src/platform_impl/linux/x11/window.rs

@@ -21,7 +21,7 @@ use super::{
     ffi, ActiveEventLoop, CookieResultExt, ImeRequest, ImeSender, VoidCookie, XConnection,
 };
 use crate::cursor::{Cursor, CustomCursor as RootCustomCursor};
-use crate::dpi::{PhysicalPosition, PhysicalSize, Position, Size};
+use crate::dpi::{PhysicalInsets, PhysicalPosition, PhysicalSize, Position, Size};
 use crate::error::{NotSupportedError, RequestError};
 use crate::event::{Event, SurfaceSizeWriter, WindowEvent};
 use crate::event_loop::AsyncRequestSerial;
@@ -82,8 +82,8 @@ impl CoreWindow for Window {
         common::xkb::reset_dead_keys();
     }
 
-    fn inner_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
-        self.0.inner_position()
+    fn surface_position(&self) -> PhysicalPosition<i32> {
+        self.0.surface_position()
     }
 
     fn outer_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
@@ -106,6 +106,10 @@ impl CoreWindow for Window {
         self.0.outer_size()
     }
 
+    fn safe_area(&self) -> PhysicalInsets<u32> {
+        self.0.safe_area()
+    }
+
     fn set_min_surface_size(&self, min_size: Option<Size>) {
         self.0.set_min_surface_size(min_size)
     }
@@ -1508,7 +1512,7 @@ impl UnownedWindow {
         }
     }
 
-    pub(crate) fn inner_position_physical(&self) -> (i32, i32) {
+    fn inner_position_physical(&self) -> (i32, i32) {
         // This should be okay to unwrap since the only error XTranslateCoordinates can return
         // is BadWindow, and if the window handle is bad we have bigger problems.
         self.xconn
@@ -1518,8 +1522,14 @@ impl UnownedWindow {
     }
 
     #[inline]
-    pub fn inner_position(&self) -> Result<PhysicalPosition<i32>, RequestError> {
-        Ok(self.inner_position_physical().into())
+    pub fn surface_position(&self) -> PhysicalPosition<i32> {
+        let extents = self.shared_state_lock().frame_extents.clone();
+        if let Some(extents) = extents {
+            extents.surface_position().into()
+        } else {
+            self.update_cached_frame_extents();
+            self.surface_position()
+        }
     }
 
     pub(crate) fn set_position_inner(
@@ -1582,6 +1592,10 @@ impl UnownedWindow {
         }
     }
 
+    fn safe_area(&self) -> PhysicalInsets<u32> {
+        PhysicalInsets::new(0, 0, 0, 0)
+    }
+
     pub(crate) fn request_surface_size_physical(&self, width: u32, height: u32) {
         self.xconn
             .xcb_connection()
@@ -1989,7 +2003,7 @@ impl UnownedWindow {
             .query_pointer(self.xwindow, util::VIRTUAL_CORE_POINTER)
             .map_err(|err| os_error!(err))?;
 
-        let window_position = self.inner_position()?;
+        let window_position = self.inner_position_physical();
 
         let atoms = self.xconn.atoms();
         let message = atoms[_NET_WM_MOVERESIZE];
@@ -2016,8 +2030,8 @@ impl UnownedWindow {
                         | xproto::EventMask::SUBSTRUCTURE_NOTIFY,
                 ),
                 [
-                    (window_position.x + xinput_fp1616_to_float(pointer.win_x) as i32) as u32,
-                    (window_position.y + xinput_fp1616_to_float(pointer.win_y) as i32) as u32,
+                    (window_position.0 + xinput_fp1616_to_float(pointer.win_x) as i32) as u32,
+                    (window_position.1 + xinput_fp1616_to_float(pointer.win_y) as i32) as u32,
                     action.try_into().unwrap(),
                     1, // Button 1
                     1,