pc.Quat
A quaternion.
Summary
Static Properties
IDENTITY | A constant quaternion set to [0, 0, 0, 1] (the identity).[read only] |
ZERO | A constant quaternion set to [0, 0, 0, 0].[read only] |
Properties
w | The w component of the quaternion. |
x | The x component of the quaternion. |
y | The y component of the quaternion. |
z | The z component of the quaternion. |
Methods
clone | Returns an identical copy of the specified quaternion. |
copy | Copies the contents of a source quaternion to a destination quaternion. |
equals | Reports whether two quaternions are equal. |
getAxisAngle | Gets the rotation axis and angle for a given quaternion. |
getEulerAngles | Converts the supplied quaternion to Euler angles. |
invert | Generates the inverse of the specified quaternion. |
length | Returns the magnitude of the specified quaternion. |
lengthSq | Returns the magnitude squared of the specified quaternion. |
mul | Returns the result of multiplying the specified quaternions together. |
mul2 | Returns the result of multiplying the specified quaternions together. |
normalize | Returns the specified quaternion converted in place to a unit quaternion. |
set | Sets the specified quaternion to the supplied numerical values. |
setFromAxisAngle | Sets a quaternion from an angular rotation around an axis. |
setFromEulerAngles | Sets a quaternion from Euler angles specified in XYZ order. |
setFromMat4 | Converts the specified 4x4 matrix to a quaternion. |
slerp | Performs a spherical interpolation between two quaternions. |
toString | Converts the quaternion to string form. |
transformVector | Transforms a 3-dimensional vector by the specified quaternion. |
Details
Static Properties
IDENTITY | A constant quaternion set to [0, 0, 0, 1] (the identity).[read only] |
ZERO | A constant quaternion set to [0, 0, 0, 0].[read only] |
Constructor
Quat([x], [y], [z], [w])
Create a new Quat object.
Parameters
x | Number | The quaternion's x component. Default value 0. If x is an array of length 4, the array will be used to populate all components. |
y | Number | The quaternion's y component. Default value 0. |
z | Number | The quaternion's z component. Default value 0. |
w | Number | The quaternion's w component. Default value 1. |
Properties
The w component of the quaternion.
var quat = new pc.Quat();
// Get w
var w = quat.w;
// Set w
quat.w = 0;
The x component of the quaternion.
var quat = new pc.Quat();
// Get x
var x = quat.x;
// Set x
quat.x = 0;
The y component of the quaternion.
var quat = new pc.Quat();
// Get y
var y = quat.y;
// Set y
quat.y = 0;
The z component of the quaternion.
var quat = new pc.Quat();
// Get z
var z = quat.z;
// Set z
quat.z = 0;
Methods
clone()
Returns an identical copy of the specified quaternion.
var q = new pc.Quat(-0.11, -0.15, -0.46, 0.87);
var qclone = q.clone();
console.log("The result of the cloning is: " + q.toString());
Returns
pc.Quat A quaternion containing the result of the cloning.copy(rhs)
Copies the contents of a source quaternion to a destination quaternion.
var src = new pc.Quat();
var dst = new pc.Quat();
dst.copy(src, src);
console.log("The two quaternions are " + (src.equals(dst) ? "equal" : "different"));
Parameters
rhs | pc.Quat | The quaternion to be copied. |
Returns
pc.Quat Self for chaining.equals(rhs)
Reports whether two quaternions are equal.
var a = new pc.Quat();
var b = new pc.Quat();
console.log("The two quaternions are " + (a.equals(b) ? "equal" : "different"));
Parameters
rhs | pc.Quat | The quaternion to be compared against. |
Returns
Boolean true if the quaternions are equal and false otherwise.getAxisAngle(axis)
Gets the rotation axis and angle for a given quaternion. If a quaternion is created with setFromAxisAngle, this method will return the same values as provided in the original parameter list OR functionally equivalent values.
var q = new pc.Quat();
q.setFromAxisAngle(new pc.Vec3(0, 1, 0), 90);
var v = new pc.Vec3();
var angle = q.getAxisAngle(v);
// Should output 90
console.log(angle)
// Should output [0, 1, 0]
console.log(v.toString());
Parameters
axis | pc.Vec3 | The 3-dimensional vector to receive the axis of rotation. |
Returns
Number Angle, in degrees, of the rotationgetEulerAngles([eulers])
Converts the supplied quaternion to Euler angles.
Parameters
eulers | pc.Vec3 | The 3-dimensional vector to receive the Euler angles. |
Returns
pc.Vec3 The 3-dimensional vector holding the Euler angles that correspond to the supplied quaternion.invert()
Generates the inverse of the specified quaternion.
// Create a quaternion rotated 180 degrees around the y-axis
var rot = new pc.Quat().setFromEulerAngles(0, 180, 0);
// Invert in place
rot.invert();
Returns
pc.Quat Self for chaining.length()
Returns the magnitude of the specified quaternion.
var q = new pc.Quat(0, 0, 0, 5);
var len = q.length();
// Should output 5
console.log("The length of the quaternion is: " + len);
Returns
Number The magnitude of the specified quaternion.lengthSq()
Returns the magnitude squared of the specified quaternion.
var q = new pc.Quat(3, 4, 0);
var lenSq = q.lengthSq();
// Should output 25
console.log("The length squared of the quaternion is: " + lenSq);
Returns
Number The magnitude of the specified quaternion.mul(rhs)
Returns the result of multiplying the specified quaternions together.
var a = new pc.Quat().setFromEulerAngles(0, 30, 0);
var b = new pc.Quat().setFromEulerAngles(0, 60, 0);
// a becomes a 90 degree rotation around the Y axis
// In other words, a = a * b
a.mul(b);
console.log("The result of the multiplication is: " a.toString());
Parameters
rhs | pc.Quat | The quaternion used as the second multiplicand of the operation. |
Returns
pc.Quat Self for chaining.mul2(lhs, rhs)
Returns the result of multiplying the specified quaternions together.
var a = new pc.Quat().setFromEulerAngles(0, 30, 0);
var b = new pc.Quat().setFromEulerAngles(0, 60, 0);
var r = new pc.Quat();
// r is set to a 90 degree rotation around the Y axis
// In other words, r = a * b
r.mul2(a, b);
console.log("The result of the multiplication is: " r.toString());
Parameters
lhs | pc.Quat | The quaternion used as the first multiplicand of the operation. |
rhs | pc.Quat | The quaternion used as the second multiplicand of the operation. |
Returns
pc.Quat Self for chaining.normalize()
Returns the specified quaternion converted in place to a unit quaternion.
var v = new pc.Quat(0, 0, 0, 5);
v.normalize();
// Should output 0, 0, 0, 1
console.log("The result of the vector normalization is: " + v.toString());
Returns
pc.Quat The result of the normalization.set(x, y, z, w)
Sets the specified quaternion to the supplied numerical values.
var q = new pc.Quat();
q.set(1, 0, 0, 0);
// Should output 1, 0, 0, 0
console.log("The result of the vector set is: " + q.toString());
Parameters
x | Number | The x component of the quaternion. |
y | Number | The y component of the quaternion. |
z | Number | The z component of the quaternion. |
w | Number | The w component of the quaternion. |
Returns
pc.Quat Self for chaining.setFromAxisAngle(axis, angle)
Sets a quaternion from an angular rotation around an axis.
var q = new pc.Quat();
q.setFromAxisAngle(pc.Vec3.UP, 90);
Parameters
axis | pc.Vec3 | World space axis around which to rotate. |
angle | Number | Angle to rotate around the given axis in degrees. |
Returns
pc.Quat Self for chaining.setFromEulerAngles(ex, ey, ez)
Sets a quaternion from Euler angles specified in XYZ order.
var q = new pc.Quat();
q.setFromEulerAngles(45, 90, 180);
Parameters
ex | Number | Angle to rotate around X axis in degrees. |
ey | Number | Angle to rotate around Y axis in degrees. |
ez | Number | Angle to rotate around Z axis in degrees. |
Returns
pc.Quat Self for chaining.setFromMat4(m)
Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a representation for orientation, only the translational part of the matrix is lost.
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
var rot = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);
// Convert to a quaternion
var q = new pc.Quat().setFromMat4(rot);
Parameters
m | pc.Mat4 | The 4x4 matrix to convert. |
Returns
pc.Quat Self for chaining.slerp(lhs, rhs, alpha)
Performs a spherical interpolation between two quaternions. The result of the interpolation is written to the quaternion calling the function.
var q1 = new pc.Quat(-0.11,-0.15,-0.46,0.87);
var q2 = new pc.Quat(-0.21,-0.21,-0.67,0.68);
var result;
result = new pc.Quat().slerp(q1, q2, 0); // Return q1
result = new pc.Quat().slerp(q1, q2, 0.5); // Return the midpoint interpolant
result = new pc.Quat().slerp(q1, q2, 1); // Return q2
Parameters
lhs | pc.Quat | The quaternion to interpolate from. |
rhs | pc.Quat | The quaternion to interpolate to. |
alpha | Number | The value controlling the interpolation in relation to the two input quaternions. The value is in the range 0 to 1, 0 generating q1, 1 generating q2 and anything in between generating a spherical interpolation between the two. |
Returns
pc.Quat Self for chaining.toString()
Converts the quaternion to string form.
var v = new pc.Quat(0, 0, 0, 1);
// Should output '[0, 0, 0, 1]'
console.log(v.toString());
Returns
String The quaternion in string form.transformVector(vec, [res])
Transforms a 3-dimensional vector by the specified quaternion.
// Create a 3-dimensional vector
var v = new pc.Vec3(1, 2, 3);
// Create a 4x4 rotation matrix
var q = new pc.Quat().setFromEulerAngles(10, 20, 30);
var tv = q.transformVector(v);
Parameters
vec | pc.Vec3 | The 3-dimensional vector to be transformed. |
res | pc.Vec3 | An optional 3-dimensional vector to receive the result of the transformation. |