From 33b9be27d39503897933726d1c5560e4ec271222 Mon Sep 17 00:00:00 2001
From: kobewi <kobewi4e@gmail.com>
Date: Mon, 1 May 2023 13:50:34 +0200
Subject: [PATCH] Some clarifications on screen-space coordinates

---
 doc/classes/CanvasItem.xml    | 1 +
 doc/classes/DisplayServer.xml | 2 +-
 doc/classes/Window.xml        | 1 +
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index af1f2be76d85..95c58ddbd6bc 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -423,6 +423,7 @@
 			<return type="Vector2" />
 			<description>
 				Returns the mouse's position in the [CanvasLayer] that this [CanvasItem] is in using the coordinate system of the [CanvasLayer].
+				[b]Note:[/b] For screen-space coordinates (e.g. when using a non-embedded [Popup]), you can use [method DisplayServer.mouse_get_position].
 			</description>
 		</method>
 		<method name="get_global_transform" qualifiers="const">
diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml
index 924e1d5d2fc6..ed9d32e881ad 100644
--- a/doc/classes/DisplayServer.xml
+++ b/doc/classes/DisplayServer.xml
@@ -821,7 +821,7 @@
 		<method name="mouse_get_position" qualifiers="const">
 			<return type="Vector2i" />
 			<description>
-				Returns the mouse cursor's current position.
+				Returns the mouse cursor's current position in screen coordinates.
 			</description>
 		</method>
 		<method name="mouse_set_mode">
diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml
index 4cc48bd70b7c..f3f3b2dd014e 100644
--- a/doc/classes/Window.xml
+++ b/doc/classes/Window.xml
@@ -563,6 +563,7 @@
 		</member>
 		<member name="position" type="Vector2i" setter="set_position" getter="get_position" default="Vector2i(0, 0)">
 			The window's position in pixels.
+			If [member ProjectSettings.display/window/subwindows/embed_subwindows] is [code]false[/code], the position is in absolute screen coordinates. This typically applies to editor plugins. If the setting is [code]false[/code], the window's position is in the coordinates of its parent [Viewport].
 		</member>
 		<member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(100, 100)">
 			The window's size in pixels.