Unexpected behavior from chaining Transform2D

[bluenote10]

Godot version: 3.1.2.stable

OS/device including version: Ubuntu 18.04

Issue description:

Chaining Transform2D calls does not behave as one would expect (both from reading the docs and general affine geometry perspective). The documentation says for:

• translated: Translates the transform by the given offset.
• scaled: Scales the transform by the given factor.
• rotated: Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors.

Thus, one would expect that the order of translated/scaled/rotated calls matters, which doesn't seem to be the case.

Steps to reproduce:

The following two calls:

print(Transform2D().scaled(Vector2(2, 2)).translated(Vector2(10, 0)))
print(Transform2D().translated(Vector2(10, 0)).scaled(Vector2(2, 2)))

both result in

((2, 0), (0, 2), (20, 0))
((2, 0), (0, 2), (20, 0))

but my expectation would have been to see the same difference as here:

Not sure if this is expected behavior (in 3D chaining transforms like that seems to work, so I was assuming the same code is valid in 2D as well).

If it is intended behavior, it would be nice to document that translated/scaled/rotated only set the corresponding parts of the transformation matrix and don't perform matrix multiplication, i.e., cannot be chained.

Minimal reproduction project: Needed?

[aaronfranke]

The way that it currently works, translated moves relative to itself (source), and scaled works as if providing a parent transform with a scale (source), same for rotated.

it would be nice to document that translated/scaled/rotated only set the corresponding parts of the transformation matrix and don't perform matrix multiplication

Well, actually scaled and rotated both do perform matrix multiplication. translated does not, but you can achieve that behavior with t.origin += whatever so there's not much of a reason to.

[bluenote10]

For complex transformation chains it would be much easier if they would all behave like matrix multiplications. That t.origin += whatever is surprising API-wise, and I'm not sure if I could apply it in general, e.g. if I had to do translate + rotate + translate.

so there's not much of a reason to [document]

If there is no way to change it, a detailed note in the docs definitely wouldn't hurt. Currently the documentation sounds like the three have identical behavior, suggesting matrix multiplication. I spend 4 hours hunting my issue, because from experiences with other affine geometry libraries and reading the docs doing matrix multiplication in only 2 out of the 3 cases was quite a pitfall.

[bluenote10]

For the record, turned into a proposal here: godotengine/godot-proposals#1336.