GLKQuaternion Reference

Framework
GLKit/GLKMath.h
Declared in
GLKMathTypes.h
GLKQuaternion.h

Overview

The GLKQuaternion type defines a structure that represents a quaternion. A quaternion is defined by a scalar component s and an XYZ vector v. Quaternions are often used in graphics programming as a compact representation of a rotation of an object in three dimensions.

The functions that manipulate GLKQuaternion structures treat the inputs as immutable, instead returning a new quaternion that represent the results of the operation.

Functions by Task

Creating Quaternions

Retrieving Information About a Quaternion

Performing Mathematical Operations on Quaternions

Applying Quaternions to Vectors

Functions

GLKQuaternionAdd

Returns the sum of two quaternions.

GLKQuaternion GLKQuaternionAdd (
   GLKQuaternion quaternionLeft,
   GLKQuaternion quaternionRight
);
Parameters
quaternionLeft

The first quaternion.

quaternionRight

The second quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionAngle

Returns the rotation angle of a quaternion.

float GLKQuaternionAngle (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

The angle of the rotation in radians (a positive angle is counterclockwise).

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionAxis

Returns the axis of rotation of a quaternion.

GLKVector3 GLKQuaternionAxis (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

The axis of rotation.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionConjugate

Returns the conjugate of a quaternion.

GLKQuaternion GLKQuaternionConjugate (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

A new quaternion that is the conjugate of the source quaternion.

Discussion

The conjugate of a quaternion has the same scalar value, but the signs of the vector components are flipped.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionInvert

Returns an inverse of a quaternion.

GLKQuaternion GLKQuaternionInvert (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

A new quaternion that is the inverse of the source quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionLength

Returns the length of a quaternion.

float GLKQuaternionLength (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

The length of the quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMake

Returns a quaternion created from its separate components.

GLKQuaternion GLKQuaternionMake (
   float x,
   float y,
   float z,
   float w
);
Parameters
x

The x component of the quaternion.

y

The y component of the quaternion.

z

The z component of the quaternion.

w

The w component of the quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithAngleAndAxis

Creates a quaternion that represents a rotation around an axis.

GLKQuaternion GLKQuaternionMakeWithAngleAndAxis (
   float radians,
   float x,
   float y,
   float z
);
Parameters
radians

The angle of the rotation in radians (a positive angle is counterclockwise).

x

The x component of the axis.

y

The y component of the axis.

z

The z component of the axis.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithAngleAndVector3Axis

Creates a quaternion that represents a rotation around an axis.

GLKQuaternion GLKQuaternionMakeWithAngleAndVector3Axis (
   float radians,
   GLKVector3 axisVector
);
Parameters
radians

The angle of the rotation in radians (a positive angle is counterclockwise).

axisVector

The axis of rotation.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithArray

Returns a quaternion created from an array of components.

GLKQuaternion GLKQuaternionMakeWithArray (
   float values[4]
);
Parameters
float values[4]

The four components that comprise the new quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithMatrix3

Creates a quaternion from a rotation matrix.

GLKQuaternion GLKQuaternionMakeWithMatrix3 (
   GLKMatrix3 matrix
);
Parameters
matrix

A rotation matrix to convert into a quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithMatrix4

Creates a quaternion from a rotation matrix.

GLKQuaternion GLKQuaternionMakeWithMatrix4 (
   GLKMatrix4 matrix
);
Parameters
matrix

A rotation matrix to convert into a quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMakeWithVector3

Returns a quaternion created from a vector and a scalar.

GLKQuaternion GLKQuaternionMakeWithVector3 (
   GLKVector3 vector,
   float scalar
);
Parameters
vector

The vector portion of the new quaternion.

scalar

The scalar portion of the new quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionMultiply

Returns the product of two quaternions.

GLKQuaternion GLKQuaternionMultiply (
   GLKQuaternion quaternionLeft,
   GLKQuaternion quaternionRight
);
Parameters
quaternionLeft

The first quaternion.

quaternionRight

The second quaternion.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionNormalize

Returns a normalized version of a quaternion.

GLKQuaternion GLKQuaternionNormalize (
   GLKQuaternion quaternion
);
Parameters
quaternion

A quaternion.

Return Value

A new quaternion, normalized to have a length of 1.0.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionRotateVector3

Returns a new vector that is calculated by applying a quaternion rotation to a vector.

GLKVector3 GLKQuaternionRotateVector3 (
   GLKQuaternion quaternion,
   GLKVector3 vector
);
Parameters
quaternion

A quaternion.

vector

A source vector.

Return Value

A new vector.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionRotateVector3Array

Applies a quaternion rotation to an array of vectors.

void GLKQuaternionRotateVector3Array (
   GLKQuaternion quaternion,
   GLKVector3 *vectors,
   size_t vectorCount
);
Parameters
quaternion

A quaternion.

vectors

On entry, an array of input vectors. On return, an array of output vectors.

vectorCount

The number of vectors in the array.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionRotateVector4

Returns a new vector calculated by applying a quaternion rotation to a vector.

GLKVector4 GLKQuaternionRotateVector4 (
   GLKQuaternion quaternion,
   GLKVector4 vector
);
Parameters
quaternion

A quaternion.

vector

A source vector.

Return Value

A new vector.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionRotateVector4Array

Applies a quaternion rotation to an array of vectors.

void GLKQuaternionRotateVector4Array (
   GLKQuaternion quaternion,
   GLKVector4 *vectors,
   size_t vectorCount
);
Parameters
quaternion

A quaternion.

vectors

On entry, an array of input vectors. On return, an array of output vectors.

vectorCount

The number of vectors in the array.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionSlerp

Returns the spherical linear interpolation of two quaternions.

GLKQuaternion GLKQuaternionSlerp (
   GLKQuaternion quaternionStart,
   GLKQuaternion quaternionEnd,
   float t
);
Parameters
quaternionStart

The starting point.

quaternionEnd

The ending point.

t

The interpolation factor.

Return Value

A new quaternion. When t=0, the result is the start quaternion. When t=1.0, the result is the end quaternion. For any other value of t, the result is a spherical linear interpolation between the two quaternions.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

GLKQuaternionSubtract

Returns the difference between two quaternions.

GLKQuaternion GLKQuaternionSubtract (
   GLKQuaternion quaternionLeft,
   GLKQuaternion quaternionRight
);
Parameters
quaternionLeft

The minuend.

quaternionRight

The subtrahend.

Return Value

A new quaternion.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKQuaternion.h

Data Types

GLKQuaternion

A representation of a quaternion.

union _GLKQuaternion
   {
   struct { GLKVector3 v; float s; };
   struct { float x, y, z, w; };
      float q[4];
}
typedef union _GLKQuaternion GLKQuaternion;
Fields
v

The vector portion of the quaternion.

s

The scalar component of the quaternion.

x

The x component of the vector portion of the quaternion.

y

The y component of the vector portion of the quaternion.

z

The z component of the vector portion of the quaternion.

w

The scalar component of the quaternion.

q

The components of the quaternion expressed as an array of elements.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKMathTypes.h

Constants

GLKQuaternionIdentity

An identity quaternion.

extern const GLKQuaternion GLKQuaternionIdentity;
Constants
GLKQuaternionIdentity

An identity quaternion.

Available in iOS 5.0 and later.

Declared in GLKQuaternion.h.