Add a Window method to return the automatically computed 2D scale factor

[Calinou]

• Related to 2d or viewport stretch mode does not scale mouse coordinates godot#34805.

Describe the project you are working on

The Godot editor 🙂

Describe the problem or limitation you are having in your project

Sometimes, you want to know the automatically computed 2D scale factor. For instance, if your project's base window size is 1280×720 (16:9) and you're playing in a 3440×1440 (21:9) window, the scale factor is 1440/720 = 2.0 as the lowest of the two dimensions (width/height) is used as a basis.

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.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Add a Window method to return the automatically computed 2D scale factor. There is already a content_scale_factor property, so I'd suggest calling it Window.get_final_scale_factor().

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

• The value should be returned as a float, with 1.0 being the original scale that is used when the stretch mode is disabled or viewport.
• The returned value should take the user-defined scale factor multiplier into account, regardless of the current stretch mode. For instance, if the automatically determined scale factor is 2.0 and the user-defined scale factor multiplier is 1.5, the value returned should be 2.0 * 1.5 = 3.0.
• The documentation should make it clear that Window.get_final_scale_factor() returns a value different than DisplayServer.screen_get_scale(), as these are unrelated concepts.

If this enhancement will not be used often, can it be worked around with a few lines of script?

The following line can be used in any script that extends Node:

var scale_factor: float = min(
		(float(get_viewport().size.x) / get_viewport().get_visible_rect().size.x),
		(float(get_viewport().size.y) / get_viewport().get_visible_rect().size.y)
)

You can check it in action in this testing project (4.x): test_scale_factor.zip

This works with all stretch modes and aspects, and also takes the user-defined scale factor into account automatically (display/window/stretch/scale). However, this isn't simple to remember and it requires a fair amount of typing for something that is needed quite often.

Is there a reason why this should be core and not an add-on in the asset library?

Given the engine already performs this kind of computation in core, it's best to expose the same value the engine is internally using to avoid any discrepancy.

[Sauermann]

Looks like this is Viewport::stretch_transform.

https://github.com/godotengine/godot/blob/6101240231600c871f5c5473872532c68ea3268c/scene/main/viewport.cpp#L942-L945

Related to #6221 which aims to make the definition of the involved sizes more precise.