Add a Viewport method to get automatically computed 2D stretch transform

`Viewport.get_stretch_transform()` returns the automatically computed
2D stretch transform. Combined with `Transform2D.get_scale()`, this is
useful when using the `canvas_items` stretch mode in a project.

There are many situations where knowing this factor is useful:

- Divide Camera2D zoom to keep the size of the 2D game world identical
  regardless of the 2D scale factor (so that UI elements can still be scaled).
- Make certain controls always drawn at 1:1 scale
  (e.g. for the crosshair in a FPS). This is done by dividing the Control
  node's scale by the scale factor.

4 files changed, 14 insertions, 1 deletions

diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml
index 333e61d03f..47ba1aea01 100644
--- a/doc/classes/Viewport.xml
+++ b/doc/classes/Viewport.xml
@@ -104,6 +104,13 @@
 				Returns the transform from the Viewport's coordinates to the screen coordinates of the containing window manager window.
 			</description>
 		</method>
+		<method name="get_stretch_transform" qualifiers="const">
+			<return type="Transform2D" />
+			<description>
+				Returns the automatically computed 2D stretch transform, taking the [Viewport]'s stretch settings into account. The final value is multiplied by [member Window.content_scale_factor], but only for the root viewport. If this method is called on a [SubViewport] (e.g., in a scene tree with [SubViewportContainer] and [SubViewport]), the scale factor of the root window will not be applied. Using [method Transform2D.get_scale] on the returned value, this can be used to compensate for scaling when zooming a [Camera2D] node, or to scale down a [TextureRect] to be pixel-perfect regardless of the automatically computed scale factor.
+				[b]Note:[/b] Due to how pixel scaling works, the transform's X scale value may differ slightly from the Y scale, even when [member Window.content_scale_aspect] is set to a mode that preserves pixel aspect ratio. If [member Window.content_scale_aspect] is [constant Window.CONTENT_SCALE_ASPECT_IGNORE], the X value may differ [i]significantly[/i] from Y due to differences between the original aspect ratio and the window aspect ratio.
+			</description>
+		</method>
 		<method name="get_texture" qualifiers="const">
 			<return type="ViewportTexture" />
 			<description>
diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml
index 02110f0162..1a4c25b916 100644
--- a/doc/classes/Window.xml
+++ b/doc/classes/Window.xml
@@ -572,7 +572,7 @@
 			Specifies how the content's aspect behaves when the [Window] is resized. The base aspect is determined by [member content_scale_size].
 		</member>
 		<member name="content_scale_factor" type="float" setter="set_content_scale_factor" getter="get_content_scale_factor" default="1.0">
-			Specifies the base scale of [Window]'s content when its [member size] is equal to [member content_scale_size].
+			Specifies the base scale of [Window]'s content when its [member size] is equal to [member content_scale_size]. See also [method Viewport.get_stretch_transform].
 		</member>
 		<member name="content_scale_mode" type="int" setter="set_content_scale_mode" getter="get_content_scale_mode" enum="Window.ContentScaleMode" default="0">
 			Specifies how the content is scaled when the [Window] is resized.
diff --git a/scene/main/viewport.cpp b/scene/main/viewport.cpp
index 54f66e8d4e..917da7d19e 100644
--- a/scene/main/viewport.cpp
+++ b/scene/main/viewport.cpp
@@ -1254,6 +1254,10 @@ Ref<World2D> Viewport::get_world_2d() const {
 	return world_2d;
 }
 
+Transform2D Viewport::get_stretch_transform() const {
+	return stretch_transform;
+}
+
 Transform2D Viewport::get_final_transform() const {
 	ERR_READ_THREAD_GUARD_V(Transform2D());
 	return stretch_transform * global_canvas_transform;
@@ -4553,6 +4557,7 @@ void Viewport::_bind_methods() {
 
 	ClassDB::bind_method(D_METHOD("set_global_canvas_transform", "xform"), &Viewport::set_global_canvas_transform);
 	ClassDB::bind_method(D_METHOD("get_global_canvas_transform"), &Viewport::get_global_canvas_transform);
+	ClassDB::bind_method(D_METHOD("get_stretch_transform"), &Viewport::get_stretch_transform);
 	ClassDB::bind_method(D_METHOD("get_final_transform"), &Viewport::get_final_transform);
 	ClassDB::bind_method(D_METHOD("get_screen_transform"), &Viewport::get_screen_transform);
 
diff --git a/scene/main/viewport.h b/scene/main/viewport.h
index a18dc1f6f0..5fb61e2220 100644
--- a/scene/main/viewport.h
+++ b/scene/main/viewport.h
@@ -514,6 +514,7 @@ public:
 	void set_global_canvas_transform(const Transform2D &p_transform);
 	Transform2D get_global_canvas_transform() const;
 
+	Transform2D get_stretch_transform() const;
 	virtual Transform2D get_final_transform() const;
 
 	void gui_set_root_order_dirty();