API Reference

Class List

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

xnumber, 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.

ynumber

The quaternion's y component. Default value 0.

znumber

The quaternion's z component. Default value 0.

wnumber

The quaternion's w component. Default value 1.

Properties

numberw

The w component of the quaternion.

var quat = new pc.Quat();

// Get w
var w = quat.w;

// Set w
quat.w = 0;
numberx

The x component of the quaternion.

var quat = new pc.Quat();

// Get x
var x = quat.x;

// Set x
quat.x = 0;
numbery

The y component of the quaternion.

var quat = new pc.Quat();

// Get y
var y = quat.y;

// Set y
quat.y = 0;
numberz

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

rhspc.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

rhspc.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

axispc.Vec3

The 3-dimensional vector to receive the axis of rotation.

Returns

number

Angle, in degrees, of the rotation.

getEulerAngles([eulers])

Converts the supplied quaternion to Euler angles.

Parameters

eulerspc.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

rhspc.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

lhspc.Quat

The quaternion used as the first multiplicand of the operation.

rhspc.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

xnumber

The x component of the quaternion.

ynumber

The y component of the quaternion.

znumber

The z component of the quaternion.

wnumber

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

axispc.Vec3

World space axis around which to rotate.

anglenumber

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

exnumber

Angle to rotate around X axis in degrees.

eynumber

Angle to rotate around Y axis in degrees.

eznumber

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

mpc.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

lhspc.Quat

The quaternion to interpolate from.

rhspc.Quat

The quaternion to interpolate to.

alphanumber

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

vecpc.Vec3

The 3-dimensional vector to be transformed.

respc.Vec3

An optional 3-dimensional vector to receive the result of the transformation.

Returns

pc.Vec3

The input vector v transformed by the current instance.