Overhaul Basis' documentation

[Mickeon]

Continuation of #86664

Bugsquad edited:
Related to #87114, and several other past efforts several other past efforts.

This PR completely overhauls Basis' documentation to the point where it is almost unrecognisable

Why?

The problems with the current documentation are summarised fairly easily:

• It is written under the assumption that the reader has a PhD in linear algebra, not for a developer.
• It explains the inner workings of Basis too much.
• It is just far, far too verbose sometimes, with no actual substance.
  • "Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix."
  • "This operator multiplies all components of the Basis, which scales it uniformly."
  • "This can be used to validate if the basis is non-distorted, which is important for physics and other use cases."
  • "Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis." _{Guys, it's the length of every axis. That's it!}

How does this PR fix it?

On the other hand, this PR does so many changes that, explaining the reasoning behind every single one of them is pretty difficult.
As more notes may be edited latter, let's get these out of the way:

• Avoid advanced math terms at all costs:
  • "Orthonormal", "orthogonal", "transformation". Avoid mentioning them unless it's very appropriate.
  • Exception to terms like "normalized" can stay. They have a clear and common purpose in Godot.
• Say "basis" consistently, avoid "basis matrix" or "matrix" alone.
  • Most users are reading this class reference for the Basis aspect of the... Basis. Mentioning its matrix a lot can potentially be confusing, unless strictly necessary for a given method.
    Advanced users know fully well it is a 3x3 matrix and will do as they please.
• Elaborate on oh-so-many methods!
  • How should I structure these parameters? How is the returned value like? What does the operation I'm doing even mean?
  • In some cases, this is just not feasible, as it would not just be too complicated, but it would bloat the documentation with information most users wouldn't care about.
    This may be frowned upon, but sometimes a link to an external article is a must.

More specific notes:

• Give full details on what Euler angles are:
  • What does each axis represent? What does the default EulerOrder do?
  • At first I was reluctant to link to Wikipedia article, but I was sold by the simple-to-follow visual examples.
• Explain how the UNIFORM basis is structured;
• Add a much-needed example for slerp();
• Expose the formula for tdotx, tdoty, and tdotz;
• Explain the difference between scripting and C++ source code's [] operator;
  • Should supersede Doc: Mention C++ uses Basis::get_column #84756.
• ...

---

Feedback is basically welcome.

This PR may contain multiple versions of the same line I was not sure about, denoted with "??". Reviewing of these lines is heavily appreciated.

Sources:

• https://datacadamia.com/geometry/skewing
• https://en.wikipedia.org/wiki/Diagonal_matrix
• https://en.wikipedia.org/wiki/Euler_angles

[TokageItLab]

Avoid advanced math terms at all costs:
"Orthonormal", "orthogonal", "transformation". Avoid mentioning them unless it's very appropriate.
Exception to terms like "normalized" can stay. They have a clear and common purpose in Godot.

I suggest that these terms be left as needed. This is because explaining things like "whether the angles of all basis vectors are perpendicular" or "whether the scales are all 1's" every time would be redundant.

Instead, I reccomend you write an explanation of the term in Matrices and transforms and link to it.

[Mickeon]

I suggest that these terms be left as needed. This is because explaining things like "whether the angles of all basis vectors are perpendicular" or "whether the scales are all 1's" every time would be redundant.

I am not sure how to feel about this, because the class reference as is in this PR does read just fine even without them.

Perhaps one solution is to add a note that later explains what those terms mean, in relation to the current method?

[Mickeon]

I updated the PR with an additional line about the meaning of a few terms, as I wait from more precise feedback from @TokageItLab

When noting the length of the vector of basis matrices, it is necessary to specify that the right-hand orthogonal system is positive. This is because focusing only on length can lead to negative scales.

It is very difficult to understand this. Can you elaborate?

[TokageItLab]

I simply point out that there is no definition of what the negative of the basis vector means in visually.

Actually, that definition may not be necessary until rendering, but if you are trying to draw/link a figure, you will need to annotate that the coordinate system of the Godot and the figure are same.

Also, it would be necessary to mention Row-major order and Column-major order. For those moving from other game engines, this can be confusing easily (and I have seen many such people). See also https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html.

[Mickeon]

Also, it would be necessary to mention Row-major order and Column-major order. For those moving from other game engines, this can be confusing easily (and I have seen many such people). See also https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html.

I suppose this can be mentioned, yeah... It does sound important.

Actually, that definition may not be necessary until rendering, but if you are trying to draw/link a figure, you will need to annotate that the coordinate system of the Godot and the figure are same.

But I am not sure about. Would it not be for granted that both coordinate systems are the same?

[TokageItLab]

As far as I know, mathematics basically uses the right-hand coordinate system, but in cases such as when a diagram created by someone working in DirectX is referenced, the left-hand coordinate system may be used and the direction of rotation, etc. may be flipped.

In order to counter such a claim from a DirectX user that the rotation is reversed, it is better to specify that Godot is in the right-hand coordinate system.

@aaronfranke previously wrote about the coordinate system for the asset pipeline https://docs.godotengine.org/en/4.1/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions, but I am not sure if it is appropriate to link to that. Perhaps you can find a more appropriate link.

[Mickeon]

Linking to more advanced "lessons" does sound good to me. The goal of this PR was to make the Basis class reference more accessible, so talking too much about advanced topics is a bit out of scope. Even my head is spinning about this...

As far as I know, mathematics basically uses the right-hand coordinate system, but in cases such as when a diagram created by someone working in DirectX is referenced, the left-hand coordinate system may be used and the direction of rotation, etc. may be flipped.

This is true... Different programs all use different coordinate systems.
As far as I Godot only uses two: one for 2D and another for 3D. In this PR, you may notice I tried to make the Basis' axes easier to imagine (The IDENTITY constant, x, y, and z descriptions). This looked good enough and in my opinion, this kind of information is MUCH more useful to be included in Transform3D's class reference (coming soon).

But if it indeed is not enough, I could pull my favourite reference sheet as a link for users to see: https://bevy-cheatbook.github.io/fundamentals/coords.html

[aaronfranke]

You could make the argument that "distorted" applies to anything that doesn't pass the is_conformal check, including non-uniform scale. I'm not sure how specifically to rephrase it.

[Mickeon]

One draft of the same sentence was in fact pointing is_comformal but I couldn't have it sounding nice or at the very least not overbearing. It needs to be mentioned though, so I need to find a way.

[Mickeon]

Thank you @TokageItLab and @aaronfranke very much for your time, here comes a second revision.

[aaronfranke]

This is misleading, coordinate system handedness has nothing to do with the conventions of how assets are oriented. They are separate things.

To make an analogy, it's like saying "The USA uses US dollars. This may be different from what you are used to, for example, they use feet and inches instead of meters". That statement would imply that US dollars imply feet and inches. No, they are completely separate things.

[Mickeon]

What could be said in this case, then?

[aaronfranke]

Actually, looking at this closer, Basis actually has no inherent handedness. I'm pretty sure that all of the same math methods will work exactly as-is if you used the same Basis code with a left-handed coordinate system. What makes Godot right-handed is its interpretation of the data we store in Basis.

The only places where conventions are encoded into Basis are 1) In the default Euler angle order YXZ which works best for Y-vertical, X-sides, Z-forward/back systems, and 2) The directions used by the looking_at method.

[Mickeon]

So the note about the coordinate system would be best suited for Transform3D, instead? Omitting it here may conflict with what @TokageItLab requested to mention above.

[TokageItLab]

Actually, that definition may not be necessary until rendering, but if you are trying to draw/link a figure, you will need to annotate that the coordinate system of the Godot and the figure are same.

As I said above, no coordinate system definition is required until rendering. However, since you seem to have links to some figures, so it would be better to indicate whether the figure and the result rendered by Godot match or not.

If we were to write in the document, it would be something like:

"The same matrix can be used for both right- and left-handed coordinate systems, what you can see there is a different drawing result. To match visual result with explanation of the direction of rotation or translation, when you refer to some illustrated documents from external link, we recommend that you refer to those drawn within the right-handed coordinate system, the same as Godot."

[aaronfranke]

To clarify, the preamble I wrote in the asset direction conventions section that Tokage linked is prerequisite information to explaining the asset direction conventions in terms of that coordinate system. So it's "Godot is X, and in terms of X, Godot is Y" not "Godot is X, and because of X, Godot is Y". An immediate minor improvement would be to remove the "For example" prefix to that sentence.

In terms of the documentation of the Basis structure, we need to make it clear specifically what documentation applies to Basis itself, what applies to its interpretation, and what applies to a specific method.

It may also be useful to mention specifically what engines don't use right-handed, instead of a vague notion of not being what you're used to. Right-handed is the dominant system, it's just a few outliers like Unity and Unreal that use left-handed.

I recommend that the text be changed to this:

Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url]. Most software is right-handed, but this is different from the Unity and Unreal engines. Built-in types like [Camera3D] use the convention of +X is right, +Y is up, and +Z is back. Other objects within this coordinate system may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial.

And yeah it's not perfect, it doesn't explicitly state that Basis is mostly handedness-independent, I don't know if this is worth mentioning, it's probably fine as long as we make the rest of the words clear that they apply to Godot, Godot built-in types, and assets, not Basis itself. Feel free to tweak if needed. Any further elaboration of direction conventions should be localized to the description of the looking_at method IMO.

Oh and also, yes as Tokage mentioned, even if the math is handedness-independent, we must ensure that any diagrams we link are consistent.

[Mickeon]

Also would like to note, I have purposely omitted looking_at from this PR because I believe it would be better to address the description of it and all other similar methods in a separate, focused PR.

[aaronfranke]

This is great! I don't see any more problems with this, it's a great improvement.

[akien-mga]

Thanks!

[Mickeon]

The late-night merge!!!!! 🌙

[akien-mga]

Cherry-picked for 4.2.2.
Cherry-picked for 4.1.4.