gitadmin
/
three.js
mirror of https://github.com/mrdoob/three.js.git


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

		<p class="desc">
			Class representing a 4D [link:https://en.wikipedia.org/wiki/Vector_space vector]. 
			A 4D vector is an ordered quadruplet of numbers (labeled x, y, z,
			and w), which can be used to represent a number of things, such as:
		</p>

		<ul>
			<li>A point in 4D space.</li>
			<li>
				A direction and length in 4D space. In three.js the length will always
				be the [link:https://en.wikipedia.org/wiki/Euclidean_distance Euclidean distance] 
				(straight-line distance) from `(0, 0, 0, 0)` to `(x, y, z, w)`
				and the direction is also measured from `(0, 0, 0, 0)` towards `(x, y,
				z, w)`.
			</li>
			<li>Any arbitrary ordered quadruplet of numbers.</li>
		</ul>

		<p>
			There are other things a 4D vector can be used to represent, however these
			are the most common uses in *three.js*.
		</p>

		<p>
			Iterating through a [name] instance will yield its components `(x, y, z,
			w)` in the corresponding order.
		</p>

		<h2>Code Example</h2>

		<code>
		const a = new THREE.Vector4( 0, 1, 0, 0 );

		//no arguments; will be initialised to (0, 0, 0, 1)
		const b = new THREE.Vector4( );

		const d = a.dot( b );
		</code>

		<h2>Constructor</h2>

		<h3>
			[name]( [param:Float x], [param:Float y], [param:Float z], [param:Float w] )
		</h3>
		<p>
			[page:Float x] - the x value of this vector. Default is `0`.<br />
			[page:Float y] - the y value of this vector. Default is `0`.<br />
			[page:Float z] - the z value of this vector. Default is `0`.<br />
			[page:Float w] - the w value of this vector. Default is `1`.<br /><br />

			Creates a new [name].
		</p>

		<h2>Properties</h2>

		<h3>[property:Boolean isVector4]</h3>
		<p>Read-only flag to check if a given object is of type [name].</p>

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

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

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

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

		<h3>[property:Float width]</h3>
		<p>Alias for [page:.z z].</p>

		<h3>[property:Float height]</h3>
		<p>Alias for [page:.w w].</p>

		<h2>Methods</h2>

		<h3>[method:this add]( [param:Vector4 v] )</h3>
		<p>Adds [page:Vector4 v] to this vector.</p>

		<h3>[method:this addScalar]( [param:Float s] )</h3>
		<p>
			Adds the scalar value s to this vector's [page:.x x], [page:.y y],
			[page:.z z] and [page:.w w] values.
		</p>

		<h3>[method:this addScaledVector]( [param:Vector4 v], [param:Float s] )</h3>
		<p>
			Adds the multiple of [page:Vector4 v] and [page:Float s] to this vector.
		</p>

		<h3>[method:this addVectors]( [param:Vector4 a], [param:Vector4 b] )</h3>
		<p>Sets this vector to [page:Vector4 a] + [page:Vector4 b].</p>

		<h3>[method:this applyMatrix4]( [param:Matrix4 m] )</h3>
		<p>Multiplies this vector by 4 x 4 [page:Matrix4 m].</p>

		<h3>[method:this ceil]()</h3>
		<p>
			The [page:.x x], [page:.y y], [page:.z z] and [page:.w w] components of
			this vector are rounded up to the nearest integer value.
		</p>

		<h3>[method:this clamp]( [param:Vector4 min], [param:Vector4 max] )</h3>
		<p>
			[page:Vector4 min] - the minimum [page:.x x], [page:.y y], [page:.z z] and
			[page:.w w] values.<br />
			[page:Vector4 max] - the maximum [page:.x x], [page:.y y], [page:.z z] and
			[page:.w w] values in the desired range<br /><br />

			If this vector's x, y, z or w value is greater than the max vector's x, y,
			z or w value, it is replaced by the corresponding value. <br /><br />
			If this vector's x, y, z or w value is less than the min vector's x, y, z
			or w value, it is replaced by the corresponding value.
		</p>

		<h3>[method:this clampLength]( [param:Float min], [param:Float max] )</h3>
		<p>
			[page:Float min] - the minimum value the length will be clamped to <br />
			[page:Float max] - the maximum value the length will be clamped to<br /><br />

			If this vector's length is greater than the max value, it is replaced by
			the max value. <br /><br />
			If this vector's length is less than the min value, it is replaced by the
			min value.
		</p>

		<h3>[method:this clampScalar]( [param:Float min], [param:Float max] )</h3>
		<p>
			[page:Float min] - the minimum value the components will be clamped to
			<br />
			[page:Float max] - the maximum value the components will be clamped to<br /><br />

			If this vector's x, y, z or w values are greater than the max value, they
			are replaced by the max value. <br /><br />
			If this vector's x, y, z or w values are less than the min value, they are
			replaced by the min value.
		</p>

		<h3>[method:Vector4 clone]()</h3>
		<p>
			Returns a new Vector4 with the same [page:.x x], [page:.y y], [page:.z z]
			and [page:.w w] values as this one.
		</p>

		<h3>[method:this copy]( [param:Vector4 v] )</h3>
		<p>
			Copies the values of the passed Vector4's [page:.x x], [page:.y y],
			[page:.z z] and [page:.w w] properties to this Vector4.
		</p>

		<h3>[method:this divideScalar]( [param:Float s] )</h3>
		<p>Divides this vector by scalar [page:Float s].</p>

		<h3>[method:Float dot]( [param:Vector4 v] )</h3>
		<p>
			Calculates the [link:https://en.wikipedia.org/wiki/Dot_product dot product] 
			of this vector and [page:Vector4 v].
		</p>

		<h3>[method:Boolean equals]( [param:Vector4 v] )</h3>
		<p>
			Returns `true` if the components of this vector and [page:Vector4 v] are
			strictly equal; `false` otherwise.
		</p>

		<h3>[method:this floor]()</h3>
		<p>
			The components of this vector are rounded down to the nearest integer
			value.
		</p>

		<h3>
			[method:this fromArray]( [param:Array array], [param:Integer offset] )
		</h3>
		<p>
			[page:Array array] - the source array.<br />
			[page:Integer offset] - (optional) offset into the array. Default is `0`.<br /><br />

			Sets this vector's [page:.x x] value to be `array[ offset + 0 ]`, [page:.y y] 
			value to be `array[ offset + 1 ]` [page:.z z] value to be `array[ offset + 2 ]` 
			and [page:.w w ] value to be `array[ offset + 3 ]`.
		</p>

		<h3>
			[method:this fromBufferAttribute]( [param:BufferAttribute attribute], [param:Integer index] )
		</h3>
		<p>
			[page:BufferAttribute attribute] - the source attribute.<br />
			[page:Integer index] - index in the attribute.<br /><br />

			Sets this vector's [page:.x x], [page:.y y], [page:.z z] and [page:.w w]
			values from the [page:BufferAttribute attribute].
		</p>

		<h3>[method:Float getComponent]( [param:Integer index] )</h3>
		<p>
			[page:Integer index] - `0`, `1`, `2` or `3`.<br /><br />

			If index equals `0` returns the [page:.x x] value. <br />
			If index equals `1` returns the [page:.y y] value. <br />
			If index equals `2` returns the [page:.z z] value.<br />
			If index equals `3` returns the [page:.w w] value.
		</p>

		<h3>[method:Float length]()</h3>
		<p>
			Computes the [link:https://en.wikipedia.org/wiki/Euclidean_distance Euclidean length] 
			(straight-line length) from `(0, 0, 0, 0)` to `(x, y, z, w)`.
		</p>

		<h3>[method:Float manhattanLength]()</h3>
		<p>
			Computes the [link:http://en.wikipedia.org/wiki/Taxicab_geometry Manhattan length] of this vector.
		</p>

		<h3>[method:Float lengthSq]()</h3>
		<p>
			Computes the square of the
			[link:https://en.wikipedia.org/wiki/Euclidean_distance Euclidean length]
			(straight-line length) from `(0, 0, 0, 0)` to `(x, y, z, w)`. If you are
			comparing the lengths of vectors, you should compare the length squared
			instead as it is slightly more efficient to calculate.
		</p>

		<h3>[method:this lerp]( [param:Vector4 v], [param:Float alpha] )</h3>
		<p>
			[page:Vector4 v] - [page:Vector4] to interpolate towards.<br />
			[page:Float alpha] - interpolation factor, typically in the closed
			interval `[0, 1]`.<br /><br />

			Linearly interpolates between this vector and [page:Vector4 v], where
			alpha is the percent distance along the line - `alpha = 0` will be this
			vector, and `alpha = 1` will be [page:Vector4 v].
		</p>

		<h3>
			[method:this lerpVectors]( [param:Vector4 v1], [param:Vector4 v2], [param:Float alpha] )
		</h3>
		<p>
			[page:Vector4 v1] - the starting [page:Vector4].<br />
			[page:Vector4 v2] - [page:Vector4] to interpolate towards.<br />
			[page:Float alpha] - interpolation factor, typically in the closed
			interval `[0, 1]`.<br /><br />

			Sets this vector to be the vector linearly interpolated between
			[page:Vector4 v1] and [page:Vector4 v2] where alpha is the percent
			distance along the line connecting the two vectors - alpha = 0 will be
			[page:Vector4 v1], and alpha = 1 will be [page:Vector4 v2].
		</p>

		<h3>[method:this negate]()</h3>
		<p>Inverts this vector - i.e. sets x = -x, y = -y, z = -z and w = -w.</p>

		<h3>[method:this normalize]()</h3>
		<p>
			Converts this vector to a [link:https://en.wikipedia.org/wiki/Unit_vector unit vector] 
			- that is, sets it equal to a vector with the same direction
			as this one, but [page:.length length] 1.
		</p>

		<h3>[method:this max]( [param:Vector4 v] )</h3>
		<p>
			If this vector's x, y, z or w value is less than [page:Vector4 v]'s x, y,
			z or w value, replace that value with the corresponding max value.
		</p>

		<h3>[method:this min]( [param:Vector4 v] )</h3>
		<p>
			If this vector's x, y, z or w value is greater than [page:Vector4 v]'s x,
			y, z or w value, replace that value with the corresponding min value.
		</p>

		<h3>[method:this multiply]( [param:Vector4 v] )</h3>
		<p>Multiplies this vector by [page:Vector4 v].</p>

		<h3>[method:this multiplyScalar]( [param:Float s] )</h3>
		<p>Multiplies this vector by scalar [page:Float s].</p>

		<h3>[method:this round]()</h3>
		<p>
			The components of this vector are rounded to the nearest integer value.
		</p>

		<h3>[method:this roundToZero]()</h3>
		<p>
			The components of this vector are rounded towards zero (up if negative,
			down if positive) to an integer value.
		</p>

		<h3>
			[method:this set]( [param:Float x], [param:Float y], [param:Float z], [param:Float w] )
		</h3>
		<p>
			Sets the [page:.x x], [page:.y y], [page:.z z] and [page:.w w] components
			of this vector.
		</p>

		<h3>[method:this setAxisAngleFromQuaternion]( [param:Quaternion q] )</h3>
		<p>
			[page:Quaternion q] - a normalized [page:Quaternion]<br /><br />

			Sets the [page:.x x], [page:.y y] and [page:.z z] components of this
			vector to the quaternion's axis and [page:.w w] to the angle.
		</p>

		<h3>[method:this setAxisAngleFromRotationMatrix]( [param:Matrix4 m] )</h3>
		<p>
			[page:Matrix4 m] - a [page:Matrix4] of which the upper left 3x3 matrix is
			a pure rotation matrix.<br /><br />

			Sets the [page:.x x], [page:.y y] and [page:.z z] to the axis of rotation
			and [page:.w w] to the angle.
		</p>

		<h3>[method:this setFromMatrixPosition]( [param:Matrix4 m] )</h3>
		<p>
			Sets this vector to the position elements of the
			[link:https://en.wikipedia.org/wiki/Transformation_matrix transformation matrix] [page:Matrix4 m].
		</p>

		<h3>
			[method:this setComponent]( [param:Integer index], [param:Float value] )
		</h3>
		<p>
			[page:Integer index] - `0`, `1`, `2` or `3`.<br />
			[page:Float value] - [page:Float]<br /><br />

			If index equals `0` set [page:.x x] to [page:Float value].<br />
			If index equals `1` set [page:.y y] to [page:Float value].<br />
			If index equals `2` set [page:.z z] to [page:Float value].<br />
			If index equals `3` set [page:.w w] to [page:Float value].
		</p>

		<h3>[method:this setLength]( [param:Float l] )</h3>
		<p>
			Sets this vector to a vector with the same direction as this one, but
			[page:.length length] [page:Float l].
		</p>

		<h3>[method:this setScalar]( [param:Float scalar] )</h3>
		<p>
			Sets the [page:.x x], [page:.y y], [page:.z z] and [page:.w w] values of
			this vector both equal to [page:Float scalar].
		</p>

		<h3>[method:this setX]( [param:Float x] )</h3>
		<p>Replaces this vector's [page:.x x] value with [page:Float x].</p>

		<h3>[method:this setY]( [param:Float y] )</h3>
		<p>Replaces this vector's [page:.y y] value with [page:Float y].</p>

		<h3>[method:this setZ]( [param:Float z] )</h3>
		<p>Replaces this vector's [page:.z z] value with [page:Float z].</p>

		<h3>[method:this setW]( [param:Float w] )</h3>
		<p>Replaces this vector's [page:.w w] value with [page:Float w].</p>

		<h3>[method:this sub]( [param:Vector4 v] )</h3>
		<p>Subtracts [page:Vector4 v] from this vector.</p>

		<h3>[method:this subScalar]( [param:Float s] )</h3>
		<p>
			Subtracts [page:Float s] from this vector's [page:.x x], [page:.y y],
			[page:.z z] and [page:.w w] components.
		</p>

		<h3>[method:this subVectors]( [param:Vector4 a], [param:Vector4 b] )</h3>
		<p>Sets this vector to [page:Vector4 a] - [page:Vector4 b].</p>

		<h3>
			[method:Array toArray]( [param:Array array], [param:Integer offset] )
		</h3>
		<p>
			[page:Array array] - (optional) array to store this vector to. If this is
			not provided, a new array will be created.<br />
			[page:Integer offset] - (optional) optional offset into the array.<br /><br />

			Returns an array [x, y, z, w], or copies x, y, z and w into the provided
			[page:Array array].
		</p>

		<h3>[method:this random]()</h3>
		<p>
			Sets each component of this vector to a pseudo-random value between `0` and
			`1`, excluding `1`.
		</p>

		<h2>Source</h2>

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