Add safe area and document coordinate systems

[madsmtm]

Resolves #2308, by adding 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 (introduced in #430) to Window::surface_position, and changed it to from screen coordinates to window coordinates, to better align how these coordinate systems work together.

Finally, I've added some SVG images and documentation to describe how these coordinate systems work together. The images should be auto-adjusting to the page theme when viewed on docs.rs. See also #3891, whether we use window coordinates or surface coordinates is currently a bit confusing.

Completing implementation on all platforms is tracked in #3910

Fixes #1122
Fixes #2308
Fixes #3742
Fixes #2066
Fixes #2347
Fixes #2235

[kchibisov]

Can macOS backend provide safe area when the transparent decorations are used? The ones where the buttons are over the main surface.

[madsmtm]

Can macOS backend provide safe area when the transparent decorations are used? The ones where the buttons are over the main surface.

Didn't even know we had WindowAttributesExtMacOS::with_titlebar_transparent, but yeah, that should be possible.

I was kinda hoping I could define safe_area to not include CSDs, but seems like I'll have to update the docs to include it as well :/.

[kchibisov]

I was kinda hoping I could define safe_area to not include CSDs, but seems like I'll have to update the docs to include it as well :/.

You just need to y offset, and that's about it from what I can say.

[madsmtm]

I have ensured that safe_area includes the title bar when with_titlebar_transparent + with_titlebar_hidden is set on macOS

[madsmtm]

I have changed fn safe_area to return the insets (dpi::PhysicalInsets { top, left, bottom, right }) instead, since I belive that will be more forwards-compatible with #3911 and other improvements (discussed on Matrix today to add insets for each type of notch).

I believe the only remaining thing is for @daxpedda to fix the web wrt. scrolling, as I wrote shortly about in #3890 (comment) (if you don't have the time rn, I'm inclined to merge this fairly soon anyhow, and then track the completion of that in #3910).

[madsmtm]

I've merged this now, though note that it's only really implemented for macOS and iOS (and Wayland, because there's no protocol for it). Web is implemented, though as noted above, it needs to be changed.

All of this remaining work (fixing the web implementation, implementing properly on the other platforms) is tracked in #3910.