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.
This commit is contained in:
Hugo Locurcio
2023-08-24 18:22:20 +02:00
parent a3080477ac
commit 0cf99cf95d
4 changed files with 14 additions and 1 deletions

View File

@ -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>