From d27adb10a0a10e2eecee4c1a60df8309cbd7e2ab Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 13 Apr 2020 09:29:11 -0400
Subject: [PATCH] surface: Document coordinate systems a bit

Mention that sizes are in application pixels.

Also, remove some X11-specific docs.
---
 gdk/gdksurface.c        | 13 +++++++------
 gdk/gdktoplevellayout.c |  3 +++
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index c02c66b66b..f01a77978c 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -473,6 +473,9 @@ gdk_surface_class_init (GdkSurfaceClass *klass)
    * @height: the new height
    *
    * Emitted when the size of @surface is changed.
+   *
+   * Surface size is reported in ”application pixels”, not
+   * ”device pixels” (see gdk_surface_get_scale_factor()).
    */
   signals[SIZE_CHANGED] =
     g_signal_new (g_intern_static_string ("size-changed"),
@@ -1981,9 +1984,8 @@ gdk_surface_get_geometry (GdkSurface *surface,
  *
  * Returns the width of the given @surface.
  *
- * On the X11 platform the returned size is the size reported in the
- * most-recently-processed configure event, rather than the current
- * size on the X server.
+ * Surface size is reported in ”application pixels”, not
+ * ”device pixels” (see gdk_surface_get_scale_factor()).
  *
  * Returns: The width of @surface
  */
@@ -2001,9 +2003,8 @@ gdk_surface_get_width (GdkSurface *surface)
  *
  * Returns the height of the given @surface.
  *
- * On the X11 platform the returned size is the size reported in the
- * most-recently-processed configure event, rather than the current
- * size on the X server.
+ * Surface size is reported in ”application pixels”, not
+ * ”device pixels” (see gdk_surface_get_scale_factor()).
  *
  * Returns: The height of @surface
  */
diff --git a/gdk/gdktoplevellayout.c b/gdk/gdktoplevellayout.c
index c68d9c2eeb..8f4a6b56aa 100644
--- a/gdk/gdktoplevellayout.c
+++ b/gdk/gdktoplevellayout.c
@@ -61,6 +61,9 @@ G_DEFINE_BOXED_TYPE (GdkToplevelLayout, gdk_toplevel_layout,
  * Used together with gdk_toplevel_present() to describe
  * how a toplevel surface should be placed and behave on-screen.
  *
+ * The size is in ”application pixels”, not
+ * ”device pixels” (see gdk_surface_get_scale_factor()).
+ *
  * Returns: (transfer full): newly created instance of #GdkToplevelLayout
  */
 GdkToplevelLayout *