The doc page for Matrix4x4.MultiplyVector (Unity - Scripting API: Matrix4x4.MultiplyVector)
says, “This function is similar to MultiplyPoint; but it transforms directions and not positions. When transforming a direction, only the rotation part of the matrix is taken into account.”
And yet, when I change the scale of the transform I use to get the Matrix4x4, the result of this function also changes.
So, it appears MultiplyVector actually takes BOTH rotation and scale into account, right? (If not, what am I misunderstanding? Why does changing the scale affect the result of this function?)
This is what I would EXPECT, based on the function’s name- but the doc’s explicitly state otherwise.
Secondary question: Does this mean I should use Matrix4x4.rotation if I REALLY want to multiply a “direction” Vector3, and take ONLY rotation into account? (I don’t see a true “multiplyDirection” function defined in the Matrix4x4 class.)
(If I get agreement in the answers, I’ll submit feedback on the doc page, and would suggest you do the same.)
The “rotation part” of a 4x4 matrix does always include the scale as well. MultiplyVector just does a 3x3 matrix multiplication with the top 3x3 section of the 4x4 matrix.
The transformation matrix contains the combined the transformations that the Transform component represents. If you just want to apply the rotation of an object, use the Quaterion and not the matrix.
There are ways to extract just the rotation from a 4x4 matrix, however even a local matrix in Unity is only composed of translation, rotation and scale, a deeper nested local to world matrix may contain a shear operation as well (a shear would be produced by non uniform scaling and rotation). This makes it quite difficult to decompose a matrix into the seperate parts. In Unity it would make much more sense to just use the Quaternion.
To answer your actual question, no, the docs are correct since it talks about the “rotation part” of the matrix which includes scale (and possible a shear). Though the docs could have mentioned explicitly that the scale affects the result, especially for those who are not familiar with matrices. Though most documentation pages are that short and could be more precise.
(Edit) Relevant detail from the comments:
"So what actually is wrong in the documentation is the following sentence from the Transform.TransformDirection documentation:
“Transforms direction from local space to world space.”
It does not transform a direction from local space to world space but just applies the wordspace rotation to a vector. If you only deal with uniform scales this is not really an issue since uniform scaling does not change the direction."