Documents the "arc-based" Quaternion constructor

[dsnopek]

This undocumented Quaternion constructor turned out to be exactly what I needed for a VR prototype I'm working on. Documenting it so it's easier for others to find! :-)

[fire]

This documents the api.

[fire]

This works on non unit sphere vectors?

[dsnopek]

This works on non unit sphere vectors?

My understanding is "no", that you need to use points on the unit sphere, however, I'm not the greatest at math. :-)

[fire]

I remember this working on points not on the surface of the unit sphere but still using the unit sphere model. Like non-normalized. Might have been my own version of it.

[dsnopek]

I did a quick test:

func _ready():
	# On the unit sphere.
	var quat1 = Quaternion(Vector3.FORWARD, Vector3.RIGHT)
	print ("Quat1 (unit): ", quat1)
	print ("Quat1 - axis: ", quat1.get_axis())
	print ("Quat1 - angle: ", quat1.get_angle())
	print ("Quat1 - is normalized: ", quat1.is_normalized())
	print ("Quat1 - use in rotation: ", quat1 * Vector3.FORWARD)

	# On a sphere with a radius of 50.
	var quat2 = Quaternion(Vector3.FORWARD * 50.0, Vector3.RIGHT * 50.0)
	print ("Quat2 (50.0): ", quat2)
	print ("Quat2 - axis: ", quat2.get_axis())
	print ("Quat2 - angle: ", quat2.get_angle())
	print ("Quat2 - is normalized: ", quat2.is_normalized())
	print ("Quat2 - use in rotation: ", quat2 * (Vector3.FORWARD * 50.0))

... which gives this output:

Quat1 (unit): (0, -0.707107, 0, 0.707107)
Quat1 - axis: (0, -1, 0)
Quat1 - angle: 1.57079637050629
Quat1 - is normalized: true
Quat1 - use in rotation: (1, 0, -0)
Quat2 (50.0): (0, -1767.767, 0, 0.707107)
Quat2 - axis: (0, -2500, 0)
Quat2 - angle: 1.57079637050629
Quat2 - is normalized: false
Quat2 - use in rotation: (0, 0, -50)

On a sphere with a radius of 50, you end up with a non-normalized quaternion that doesn't give right result when used in a rotation.

So, it looks like it does need to be on the unit sphere. However, if you do have points on a non unit sphere, then you just need to normalize both vectors before passing them to the Quaternion() constructor.

[YuriSizov]

Thanks!

[YuriSizov]

Cherry-picked for 4.0.1.