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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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.

    Import Statement