Fix ParticlesMaterial spread.

[mortarroad]

Fixes #47145
For 3.x: #47310

Instead of doing some butchery with atan and then manipulating angles, we simply rotate the vector.

[QbieShay]

I don't think "up" is a good name: people will most likely will assign the y vector and expect it to work.

I'm trying to think of something different, but I'd also like to do some research in math first to determine if there is a mathematical way to pick a random vec2 in a plane that doesn't have defined axes, so that we don't need to expose this variable at all.

[mortarroad]

Well, setting up to be the y axis will always work, in the sense that it will still be emitting in the chosen direction.

Also, we need an up axis, because we have the flatness property, and the up axis determines along which axis it should get flatter.

But I agree, the distribution could be better, currently it is quite rectangular.

[QbieShay]

@mortarroad after some brainstorming with a friend we came up with picking the vector like this:

(x, y, z) -> (-y, z, x)

Can you try if this looks better?

[mortarroad]

@QbieShay Is that a formula for deriving the up vector from the direction?
If so, it won't work either:
Let direction = (1, 1, -1).
Then up = (-1, -1, 1), which is parallel to direction.

[QbieShay]

aw :( I'm still not sure about this. I suppose in this case we can restore the singularity, but instead place it on the X axis?

Alternatively I think we can call this property "basis vector" and give it a meaningful description such as "used to calculate the angles for particles. please don't make it the same direction as the direction vector. Orthogonal to the direction vector would be best."

[mortarroad]

Emitting either happens in the XZ plane, in which Y is a good choice for up, or mostly along Y, in which X or Z is a good choice for up.
There's no good solution here.
Maybe we can automatically set up to be Z, if the user chooses Y as the direction in the editor.

I still think "up" is the right name. Everything else would be confusing.

A fitting description could be:
"A vector perpendicular to direction, along which spread is applied. The second implicit vector for applying the spread is orthogonal to both up and direction."

[QbieShay]

I disagree with "up" being a good choice. It's confusing: it's not necessarily pointing up. What about spread normal?

[mortarroad]

Renamed up to spread_normal.
Added docs for spread_normal.

[clayjohn]

Looks good to me! Let's just get @QbieShay's approval before merging. This will be a nice addition to 3.4 as well

[QbieShay]

Hey @mortarroad. First of all, thanks for all the time you spent on this. I'm super sorry, but upon reviewing this code, and the addition to a user facing variable, I'm under the impression that your original implementation was the best one. I have given it more thought, and I don't believe that there are many cases for people smoothly rotating the direction of the particle shader to justify adding a user facing parameters.

Sorry again for changing my mind, and thanks for your time!

[mortarroad]

Are you sure?
I mean, the user can just leave the variable at its default value without having to care about it.

But if you're sure, I'll just remove it and have it pick either Y or X at the up vector automatically as in the original patch.

[QbieShay]

Yes I think that would be best. Thanks for your patience 🙏

[akien-mga]

Thanks! And congrats for your first merged Godot contribution 🎉