Streamline Transform2D Hierarchy and Coordinate Systems

[Sauermann]

Describe the project you are working on

The Godot editor

Describe the problem or limitation you are having in your project

The current status of the different 2D coordinate systems and the Transform2D between them is in a state that has grown over the years and works in most but not all cases. Interfaces between them do not follow a strict logic and could be improved.
The used nomenclature is difficult to learn for new users, because it doesn't follow some kind of convention.

The following problems become immediately visible from the following graphic, which displays all currently available get_..._transform() functions:

• _get_input_pre_xform() is not available to the user, so it is impossible to properly get a complete chain of transforms.
• CanvasItem::get_screen_transform() ignores several transforms, which results in noticeable bugs, when positioning Popups.
• Viewport::get_final_transform() has a non-descriptive name, that is not intuitive for new users.

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

This proposal is intended as a design document, ready to be implemented, for one of the topics of #3866.

This proposal suggests to introduce the following single rule, that is binding for all get_xxx_transform() functions:

The function "Caller::get_xxx_transform()" either returns a transform, that belongs to the "Caller" or it returns the Transform2D from the parent "xxx"-Coordinate System to the "Caller"s coordinate system.

The following four coordinate systems are currently used and this will not change, since every one of the is needed:

• Item Coordinates:
  They are needed, because they represent the coordinates of CanvasItems.
• Canvas Coordinates:
  They are needed, because they represent the world of the CanvasItems.
• Viewport Coordinates:
  They are needed, because CanvasLayer, CanvasItem and Window behave differrently as SceneTree children.
• Screen Coordinates:
  They are needed, because they represent the location on the monitor display. (They can be interpreted as Viewport Coordinates of the Window Manager)

Benefits of the proposal:

• This helps to infer the meaning of the transform function in a simple way from the name, which will reduce confusion about which transform functions to use.
• This makes it possible to easily get transforms between all different Coordinate Systems, which is currently not possible.
• Having a clear structure the transforms between the different Coordinate Systems will help to investigate and solve the current problems with transforms.
• Get rid of transforms, that don't end in one of the standardized coordinate systems.

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

This proposal intends to change the names and meaning of transform-functions., in order to create a central backbone for transform calculations. Other functions (like get_global_position) currently implement their own transform calculation and this proposal is intended as a first step in order to move all transform calculations into a single place.

Here is the list of the new suggested transform functions:

• CanvasItem::get_transform():
  Items own transform
• CanvasItem::get_canvas_transform() (== CanvasItem::get_global_transform()):
  Canvas Coordinates -> Item Coordinates
• CanvasItem::get_viewport_transform() (== CanvasItem::get_global_transform_with_canvas()):
  Viewport Coordinates -> Item Coordinates
• CanvasItem::get_popup_transform():
  Coordinates for a Popup at the location of the CanvasItem -> Item Coordinates (might be WindowManager or Viewport coordinates)
• CanvasLayer::get_transform():
  Layers own transform
• Viewport::get_canvas_transform():
  Viewports own canvas transform
• Viewport::get_global_canvas_transform():
  Viewports own global canvas transform
• Viewport::get_parent_viewport_transform():
  Parent Viewport Coordinates -> Viewport Coordinates
• Viewport::get_screen_transform():
  Window Manager Screen Coordinates -> Viewport Coordinates

The following graphic shows them.

While I am willing to implement this, currently there is no PR for this proposal, since I want to evaluate, if this change would have a chance of being merged.

The necessary code changes consist of:

• Renaming functions (easy to do)
• Investigating and solving the places, where the changed functions are used (about 10-15 places) which is a manageable amount.

Disappearing functions

Some functions will disappear without replacement and here is a list of how this proposal will work with this change:

• CanvasItem::get_viewport_transform() is currently not used within the code base, so there is nothing to do.
• Viewport::get_final_transform() will become an Viewport-private function, since it will no longer be used outside of Viewport.

Related Topics

The created graphics can be used in https://docs.godotengine.org/en/latest/tutorials/2d/2d_transforms.html

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

As shown in godotengine/godot#30950 (comment), dealing with the different coordinate systems, can not easily be done by other means.

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

Transform2D is a central aspect of Godot CanvasItem positioning.