iOS Developer Library

Developer

GLKit Framework Reference GLKQuaternion Reference

Options
Deployment Target:

On This Page

GLKQuaternion Reference

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

  • Returns a quaternion created from its separate components.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns a quaternion created from an array of components.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionMakeWithArray ( float values[4] );

    Parameters

    float values[4]

    The four components that comprise the new quaternion.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns a quaternion created from a vector and a scalar.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Creates a quaternion that represents a rotation around an axis.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Creates a quaternion that represents a rotation around an axis.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Creates a quaternion from a rotation matrix.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionMakeWithMatrix3 ( GLKMatrix3 matrix );

    Parameters

    matrix

    A rotation matrix to convert into a quaternion.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Creates a quaternion from a rotation matrix.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionMakeWithMatrix4 ( GLKMatrix4 matrix );

    Parameters

    matrix

    A rotation matrix to convert into a quaternion.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the length of a quaternion.

    Declaration

    Objective-C

    float GLKQuaternionLength ( GLKQuaternion quaternion );

    Parameters

    quaternion

    A quaternion.

    Return Value

    The length of the quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the axis of rotation of a quaternion.

    Declaration

    Objective-C

    GLKVector3 GLKQuaternionAxis ( GLKQuaternion quaternion );

    Parameters

    quaternion

    A quaternion.

    Return Value

    The axis of rotation.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the rotation angle of a quaternion.

    Declaration

    Objective-C

    float GLKQuaternionAngle ( GLKQuaternion quaternion );

    Parameters

    quaternion

    A quaternion.

    Return Value

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

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns a normalized version of a quaternion.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionNormalize ( GLKQuaternion quaternion );

    Parameters

    quaternion

    A quaternion.

    Return Value

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

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns an inverse of a quaternion.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionInvert ( GLKQuaternion quaternion );

    Parameters

    quaternion

    A quaternion.

    Return Value

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

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the conjugate of a quaternion.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the sum of two quaternions.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionAdd ( GLKQuaternion quaternionLeft, GLKQuaternion quaternionRight );

    Parameters

    quaternionLeft

    The first quaternion.

    quaternionRight

    The second quaternion.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the difference between two quaternions.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionSubtract ( GLKQuaternion quaternionLeft, GLKQuaternion quaternionRight );

    Parameters

    quaternionLeft

    The minuend.

    quaternionRight

    The subtrahend.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the product of two quaternions.

    Declaration

    Objective-C

    GLKQuaternion GLKQuaternionMultiply ( GLKQuaternion quaternionLeft, GLKQuaternion quaternionRight );

    Parameters

    quaternionLeft

    The first quaternion.

    quaternionRight

    The second quaternion.

    Return Value

    A new quaternion.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Returns the spherical linear interpolation of two quaternions.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Objective-C

    GLKVector3 GLKQuaternionRotateVector3 ( GLKQuaternion quaternion, GLKVector3 vector );

    Parameters

    quaternion

    A quaternion.

    vector

    A source vector.

    Return Value

    A new vector.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Applies a quaternion rotation to an array of vectors.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Objective-C

    GLKVector4 GLKQuaternionRotateVector4 ( GLKQuaternion quaternion, GLKVector4 vector );

    Parameters

    quaternion

    A quaternion.

    vector

    A source vector.

    Return Value

    A new vector.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

  • Applies a quaternion rotation to an array of vectors.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Availability

    Available in iOS 5.0 and later.

Data Types

  • A representation of a quaternion.

    Declaration

    Objective-C

    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.

Constants

  • An identity quaternion.

    Declaration

    Objective-C

    extern const GLKQuaternion GLKQuaternionIdentity;

    Constants

    • GLKQuaternionIdentity

      GLKQuaternionIdentity

      An identity quaternion.

      Available in iOS 5.0 and later.