Overhaul CanvasItem documentation (no draw methods)

[Mickeon]

Related to #89256, #87440 and many others.

I forgot to ever make this pull request, this has been good enough for a while. Would be nice to merge before the above PRs, actually. I feel like this is a better starting point than the Node2D documentation overhaul.

This PR aims to overhaul CanvasItem's class reference in an attempt to be more... comprehensible and easy to understand. Reasons are the same as prior PRs so I'm not sure I should explain myself too much here.

This PR specifically avoids all of the draw methods in order to make it easier to merge sooner. These are tackled separately. See #93751.

[Mickeon]

Insane that this description has been left like this for so long. I don't even have any idea on what this is trying to say.

[KoBeWi]

CC @Sauermann

[Sauermann]

I will try to explain the idea for this description in the hopes, that someone will come up with a better way to express the content.

Godot uses different 2D coordinate systems. e.g. CanvasItem, Viewport, ....

When you want to convert a coordinate from one coordinate system to a different coordinate system, you use a Transform2D.
The fixed transform2D between CanvasItem and Viewport for example allows you to convert all coordinates relative to the CanvasItem to coordinates relative to the viewport.

In short: viewport coordinate = transform * canvas item coordinate.

Some of the coordinate systems are easy to name:

• the coordinate system of the CanvasItem
• the coordinate system of the Viewport
• the coordinate system of the Screen

Others are not easy to name, when one wants to be precise, like both coordinate systems that get_viewport_transform adresses.
CanvasItem.get_viewport_transform is in my opinion one of the most difficult to explain transform function and I believe, that it has nearly no use-case and should at some point in the future be removed from the API.
It is not even used in the code-base. (See my analysis and proposal here: godotengine/godot-proposals#4250)

To better visualize, what that transform does, have a look at the the second green bar from the bottom in the graphic here (click that graphic to enlarge):
https://docs.godotengine.org/en/latest/contributing/development/core_and_modules/2d_coordinate_systems.html

The current description is my attempt of precisely naming the two coordinate systems in the shortest possible way.

[KoBeWi]

@Mickeon Can you update the description based on the comment above, or do you think it's fine as is? (I assume it's not, given your first comment; users that don't know the explanation might be confused too)

[Mickeon]

As of answering right now, I don't have the time to come up with an updated description.
No, it's not fine indeed... but I am keeping track of the above, immensely detailed explanation.

[Mickeon]

What I can maybe say is as follows, as I right now don't have a concrete usage example:

Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport embedder's coordinate system. See also [method Viewport.get_final_transform] and [method Node.get_viewport].

Viewport's get_final_transform does the same conversion to the embedder's coordinate system, but from the Viewport's transform.
I did not touch these "transform conversion" methods in this PR too much, but I guess I'll have to reword get_canvas_transform as well.
If the purpose of the get_viewport_transform method is so arcane, it may be a good idea to deprecate it sometime soon.

[KoBeWi]

Not sure if the comma should be here, but it sounds better.

[Sauermann]

For reference:

• Deprecate CanvasItem::get_viewport_transform #104327

[Rindbee]

Some are relative transforms (Apply the transformation ending to or starting from this node), and some are intermediate transforms (for caching purposes, not directly related to the current node it is not a transformation of one node relative to another).

Currently Viewport::get_global_canvas_transform() is an intermediate transform. It may be better to rename it to Viewport::get_base_canvas_transform().

From the perspective of relative transformation, this method is more like get_global_canvas_transform(), can be added in CanvasLayer and Viewport.

[Mickeon]

Alternative:

Suggested change

	Returns [code]true[/code] if the layer at the given index is set in [member visibility_layer].
	Returns [code]true[/code] if the given [param layer] bit is set in [member visibility_layer].

[Mickeon]

Alternative:

Suggested change

	Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also [method Node.move_child].
	Moves this node below its siblings. This usually causes the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also [method Node.move_child].

[Mickeon]

This is actually more complete than I envisioned it to be. It's good to be looked at as is, too.

[Mickeon]

Rebased with no changes.

[Calinou]

Looks good to me.

[Mickeon]

This PR has been neglected for so long, that other PRs have come through to conflict with visible & y_sort_enabled's description. I have not changed these in the PR (anymore) to avoid invalidating a localization string. I would gladly rewrite them, but I do not want this PR to take even longer to review.

@Calinou 's suggestions have been accepted, assuming accuracy, with a few slight changes.

[akien-mga]

Thanks!