Add warning about broken rotations to Transform::look_at() docs

[tim-blackbird]

Add the following note to Transform::look_at() and Transform::looking_at(): "Produces a broken rotation if the resulting forward direction is parralel with up."

[alice-i-cecile]

I don't think this is the right fix. IMO we should fix the underlying math instead; this is a nasty bug.

Nit: "parallel" is the spelling :)

[tim-blackbird]

No math to fix I'm afraid. There' is just no way to create a rotation from two parallel vectors.
I rewrote the doc to make that more obvious. Maybe this is a good spot for a debug assertion?

Nit: "parallel" is the spelling :)

Gah! I've made this mistake way to many times the last few weeks. Heck, I wrote it that way again typing the above, haha

[Carter0]

Is this because of the Gimbal Locking problem?

https://en.wikipedia.org/wiki/Gimbal_lock#:~:text=Gimbal%20lock%20is%20the%20loss,a%20degenerate%20two%2Ddimensional%20space.

[alice-i-cecile]

Ugh, right. Can we return an Option or a Result then?

[tim-blackbird]

Is this because of the Gimbal Locking problem?

It's similar. We need two direction vectors and them being parallel effectively removes one, like the axes in gimbal lock being parallel effectively removing one axis.

Ugh, right. Can we return an Option or a Result then?

If you don't mind I add 62 instances of .unwrap() to the examples, haha

[alice-i-cecile]

Hmm, right lol. Can we make a fallible variant which returns a Result then, and then point to it in these docs?

[atlv24]

Could use Vec3A::any_orthonormal_vector to generate an up direction if up==forward. Might be preferable to panicking, otherwise its totally possible for a game to crash just because you stand above an entity that looks at you for example. I'd rather a random up be picked than get a crash.

[rparrett]

Linking a related issue: #3736

[MatrixDev]

No math to fix I'm afraid. There' is just no way to create a rotation from two parallel vectors.

Unity somehow can calculate rotation so there must be a solution. Here is an example:

transform.position = new Vector3(0.0f, 20.0f, 0.0f);
transform.LookAt(Vector3.zero, Vector3.up);

And result:

position = (0.00, 20.00, 0.00)
rotation before = (0.00000, 0.00000, 0.00000, 1.00000)
rotation after = (0.70711, 0.00000, 0.00000, 0.70711)

[tim-blackbird]

Unity returns a partially randomized rotation instead.
See #7817 for an alternative PR that does that.

[alice-i-cecile]

I prefer #7817: reducing mysterious footguns is better than documenting them.