javascript
/
three.js
mirror of https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
							<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<base href="../../" />
		<script src="list.js"></script>
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>[name]</h1>

		<div class="desc">Implementation of a <a href="http://en.wikipedia.org/wiki/Quaternion">quaternion</a>. This is used for rotating things without encountering the dreaded <a href="http://en.wikipedia.org/wiki/Gimbal_lock">gimbal lock</a> issue, amongst other advantages.</div>


		<h2>Example</h2>

		<code>var quaternion = new THREE.Quaternion();
		quaternion.setFromAxisAngle( new THREE.Vector3( 0, 1, 0 ), Math.PI / 2 );

		var vector = new THREE.Vector3( 1, 0, 0 );
		vector.applyQuaternion( quaternion );
		</code>


		<h2>Constructor</h2>


		<h3>[name]( [page:Float x], [page:Float y], [page:Float z], [page:Float w] )</h3>
		<div>
		x - x coordinate<br />
		y - y coordinate<br />
		z - z coordinate<br />
		w - w coordinate
		</div>


		<h2>Properties</h2>

		<h3>[property:Float x]</h3>

		<h3>[property:Float y]</h3>

		<h3>[property:Float z]</h3>

		<h3>[property:Float w]</h3>


		<h2>Methods</h2>

		<h3>[method:Quaternion set]( [page:Float x], [page:Float y], [page:Float z], [page:Float w] ) [page:Quaternion this]</h3>
		<div>
		Sets values of this quaternion.
		</div>

		<h3>[method:Quaternion copy]( [page:Quaternion q] ) [page:Quaternion this]</h3>
		<div>
		Copies values of *q* to this quaternion.
		</div>

		<h3>[method:Quaternion fromArray]( [page:Array array], [page:Integer offset] ) [page:Quaternion this]</h3>
		<div>
		array -- Array of format (x, y, z, w) used to construct the quaternion.<br />
		offset -- An optional offset into the array.
		</div>
		<div>
		Sets this quaternion's component values from an array.
		</div>

		<h3>[method:Quaternion setFromEuler]( [page:Euler euler] ) [page:Quaternion this]</h3>
		<div>
		Sets this quaternion from rotation specified by Euler angle.
		</div>

		<h3>[method:Quaternion setFromAxisAngle]( [page:Vector3 axis], [page:Float angle] ) [page:Quaternion this]</h3>
		<div>
		Sets this quaternion from rotation specified by axis and angle.<br />
		Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/angleToQuaternion/index.htm].<br />
		*Axis* is asumed to be normalized, *angle* is in radians.
		</div>

		<h3>[method:Quaternion setFromRotationMatrix]( [page:Matrix4 m] ) [page:Quaternion this]</h3>
		<div>
		Sets this quaternion from rotation component of *m*.<br />
		Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm].
		</div>

		<h3>[method:Quaternion setFromUnitVectors]( [page:Vector3 vFrom], [page:Vector3 vTo] ) [page:Quaternion this]</h3>
		<div>
		Sets this quaternion to the rotation required to rotate direction vector *vFrom* to direction vector *vTo*.<br />
		Adapted from [link:http://lolengine.net/blog/2013/09/18/beautiful-maths-quaternion-from-vectors].<br />
		*vFrom* and *vTo* are assumed to be normalized.
		</div>

		<h3>[method:Quaternion inverse]() [page:Quaternion this]</h3>
		<div>
		Inverts this quaternion.
		</div>

		<h3>[method:Float length]() [page:Quaternion this]</h3>
		<div>
		Computes length of this quaternion.
		</div>

		<h3>[method:Quaternion normalize]() [page:Quaternion this]</h3>
		<div>
		Normalizes this quaternion.
		</div>

		<h3>[method:Quaternion multiply]( [page:Quaternion b] ) [page:Quaternion this]</h3>
		<div>
		Multiplies this quaternion by *b*.
		</div>

		<h3>[method:Quaternion multiplyQuaternions]( [page:Quaternion a], [page:Quaternion b] ) [page:Quaternion this]</h3>
		<div>
		Sets this quaternion to *a x b*<br />
		Adapted from [link:http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/code/index.htm].
		</div>

		<h3>[method:Quaternion multiplyVector3]( [page:Vector3 vector], [page:Vector3 dest] ) [page:Quaternion this]</h3>
		<div>
		Rotates *vector* by this quaternion into *dest*.<br />
		If *dest* is not specified, result goes to *vec*.
		</div>

		<h3>[method:Float lengthSq]() [page:Quaternion this]</h3>
		<div>
		Calculates the squared length of the quaternion.
		</div>

		<h3>[method:Quaternion conjugate]() [page:Quaternion this]</h3>
		<div>
		Returns the rotational conjugate of this quaternion. The conjugate of a quaternion
		represents the same rotation in the opposite direction about the rotational axis.
		</div>

		<h3>[method:Quaternion slerp]( [page:Quaternion quaternionB], [page:float t] ) [page:Quaternion this]</h3>
		<div>
		quaternionB -- The other quaternion rotation<br />
		t -- Normalized 0 to 1 interpolation factor
		</div>
		<div>
		Handles the spherical linear interpolation between quaternions. *t* represents the amount of rotation
		between this quaternion (where *t* is 0) and quaternionB (where *t* is 1). This quaternion is set to
		the result. Also see the static version of the *slerp* below.
		</div>
		<code>
		// rotate a mesh towards a target quaternion
		mesh.quaternion.slerp( endQuaternion, 0.01 );
		</code>

		<h3>[method:Boolean equals]( [page:Quaternion v] ) [page:Quaternion this]</h3>
		<div>
		v -- Quaternion that this quaternion will be compared to.
		</div>
		<div>
		Compares each component of *v* to each component of this quaternion to determine if they
		represent the same rotation.
		</div>

		<h3>[method:Quaternion clone]() [page:Quaternion this]</h3>
		<div>
		Clones this quaternion.
		</div>

		<h3>[method:Array toArray]( [page:Array array], [page:Integer offset] ) [page:Quaternion this]</h3>
		<div>
		array -- An optional array to store the quaternion.<br/>
		offset -- An optional offset into the output array.
		</div>
		<div>
		Returns the numerical elements of this quaternion in an array of format (x, y, z, w).
		</div>

		<h2>Static Methods</h2>

		<h3>[method:Quaternion slerp]( [page:Quaternion qStart], [page:Quaternion qEnd], [page:Quaternion qTarget], [page:Float t] )</h3>
		<div>
		qStart -- The starting quaternion (where *t* is 0)<br />
		qEnd -- The ending quaternion (where *t* is 1)<br />
		qTarget -- The target quaternion that gets set with the result<br />
		t -- Normalized 0 to 1 interpolation factor
		</div>
		<div>
		Unlike the normal method, the static version of slerp sets a target quaternion to the result of the slerp operation.
		</div>
		<code>
		// Code setup
		var startQuaternion = new THREE.Quaternion().set( 0, 0, 0, 1 ).normalize();
		var endQuaternion = new THREE.Quaternion().set( 1, 1, 1, 1 ).normalize();
		var t = 0;
		</code>
		<code>
		// Update a mesh's rotation in the loop
		t = ( t + 0.01 ) % 1; // constant angular momentum
		THREE.Quaternion.slerp( startQuaternion, endQuaternion, mesh.quaternion, t );
		</code>

		<h3>[method:Quaternion slerpFlat]( [page:Array dst], [page:Integer dstOffset], [page:Array src0], [page:Integer srcOffset0], [page:Array src1], [page:Integer srcOffset1], [page:Float t] )</h3>
		<div>
		dst -- The output array.<br />
		dstOffset -- An offset into the output array.<br />
		src0 -- The source array of the starting quaternion.<br />
		srcOffset0 -- An offset into the array *src0*.<br />
		src1 -- The source array of the target quatnerion.<br />
		srcOffset1 -- An offset into the array *src1*.<br />
		t -- Interpolation factor 0 at start, 1 at end.
		</div>
		<div>
		Like the static *slerp* method above, but operates directly on flat arrays of numbers.
		</div>

		<!-- Note: Do not add non-static methods to the bottom of this page. Put them above the <h2>Static Methods</h2> -->

		<h2>Source</h2>

		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
	</body>
</html>