From 0cf99cf95d098392d7d1943aac37b12bd831a1d9 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Thu, 24 Aug 2023 18:22:20 +0200 Subject: [PATCH] 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. --- doc/classes/Viewport.xml | 7 +++++++ doc/classes/Window.xml | 2 +- scene/main/viewport.cpp | 5 +++++ scene/main/viewport.h | 1 + 4 files changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 333e61d03ff5..47ba1aea0158 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. + + + + 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. + + diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 02110f01628b..1a4c25b91660 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]. - 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]. Specifies how the content is scaled when the [Window] is resized. diff --git a/scene/main/viewport.cpp b/scene/main/viewport.cpp index 54f66e8d4e68..917da7d19e93 100644 --- a/scene/main/viewport.cpp +++ b/scene/main/viewport.cpp @@ -1254,6 +1254,10 @@ Ref 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 a18dc1f6f0f3..5fb61e2220b4 100644 --- a/scene/main/viewport.h +++ b/scene/main/viewport.h @@ -514,6 +514,7 @@ class Viewport : public Node { 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();