From 314cad0d8921054c14ce3a7e5a103b03116af214 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Wed, 11 Dec 2019 16:48:20 +0100
Subject: [PATCH] Platform: document how to calculate content scaling in a
 x-platform way.

---
 doc/snippets/MagnumPlatform.cpp       | 9 +++++++++
 src/Magnum/Platform/Sdl2Application.h | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/doc/snippets/MagnumPlatform.cpp b/doc/snippets/MagnumPlatform.cpp
index 04a323444..665686fa6 100644
--- a/doc/snippets/MagnumPlatform.cpp
+++ b/doc/snippets/MagnumPlatform.cpp
@@ -83,6 +83,8 @@ namespace C {
 
 struct MyApplication: Platform::Application {
     MyApplication(const Arguments& arguments);
+
+    void foo();
 };
 
 /* [configuration] */
@@ -95,6 +97,13 @@ MyApplication::MyApplication(const Arguments& arguments):
 }
 /* [configuration] */
 
+void MyApplication::foo() {
+/* [Sdl2Application-dpi-scaling] */
+Vector2 scaling = Vector2{framebufferSize()}*dpiScaling()/Vector2{windowSize()};
+/* [Sdl2Application-dpi-scaling] */
+static_cast<void>(scaling);
+}
+
 }
 
 namespace D {
diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h
index bf54e4402..9bc616870 100644
--- a/src/Magnum/Platform/Sdl2Application.h
+++ b/src/Magnum/Platform/Sdl2Application.h
@@ -383,6 +383,12 @@ The default is depending on the platform:
     @ref Platform-EmscriptenApplication-dpi "EmscriptenApplication DPI awareness docs"
     for more information.
 
+With @ref windowSize(), @ref framebufferSize() and @ref dpiScaling() having a
+different relation on each platform, the way to calculate context scaling
+consistently everywhere is using this expression:
+
+@snippet MagnumPlatform.cpp Sdl2Application-dpi-scaling
+
 If your application is saving and restoring window size, it's advisable to take
 @ref dpiScaling() into account: