Quaternions

Quaternions — Quaternions to describe rotations in 3D space

Synopsis

                    MiaQuaternion;
typedef             RotMatrix;
MiaQuaternion *     mia_quaternion_copy                 (MiaQuaternion *dest,
                                                         const MiaQuaternion *src);
MiaQuaternion *     mia_quaternion_dup                  (const MiaQuaternion *org);
gboolean            mia_quaternion_equal                (const MiaQuaternion *a,
                                                         const MiaQuaternion *b);
void                mia_quaternion_get_rotation         (MiaQuaternion *self,
                                                         RotMatrix m);
MiaQuaternion *     mia_quaternion_multby               (MiaQuaternion *self,
                                                         MiaQuaternion *other);
MiaQuaternion *     mia_quaternion_new                  (gfloat x,
                                                         gfloat y,
                                                         gfloat z,
                                                         gfloat w);
MiaQuaternion *     mia_quaternion_new_from_eulerrot    (const MiaVector3d *axis,
                                                         gfloat angle);
gfloat              mia_quaternion_norm                 (const MiaQuaternion *self);
void                mia_quaternion_normalize            (MiaQuaternion *self);
gboolean            mia_quaternion_test                 (void);
void                mia_quaternion_xmlio_read           (ParserState *state,
                                                         const gchar *property);
gboolean            mia_quaternion_xmlio_write          (xmlNodePtr root,
                                                         xmlNsPtr ns,
                                                         const gchar *tag,
                                                         const MiaQuaternion *q);

Description

MiaQuaternion and the related functions describe and handle rotations in 3D space that are specifically suited for visualization.

Details

MiaQuaternion

typedef struct _MiaQuaternion MiaQuaternion;

This defines a Quaternion and is used to describe a rotation in 3D space.


RotMatrix

typedef float RotMatrix[4][4];

A 4x4 matrix used for rotations.


mia_quaternion_copy ()

MiaQuaternion *     mia_quaternion_copy                 (MiaQuaternion *dest,
                                                         const MiaQuaternion *src);

Copy one quaternion into another one. The destination quaternion must already be properly created.

dest :

destination quaternion to copy to

src :

source quaternion to copy from

Returns :

the destination quaternion

mia_quaternion_dup ()

MiaQuaternion *     mia_quaternion_dup                  (const MiaQuaternion *org);

Create a duplicate of a quaternion. It must be destroyed by calling calling g_object_unref()

org :

a quaterion

Returns :

a newly created copy of the quaternion.

mia_quaternion_equal ()

gboolean            mia_quaternion_equal                (const MiaQuaternion *a,
                                                         const MiaQuaternion *b);

Test if two quaternions are exactly equal.

a :

left hand value for comparison

b :

right hand value for comparison

Returns :

TRUE if equal, FALSE otherwise

mia_quaternion_get_rotation ()

void                mia_quaternion_get_rotation         (MiaQuaternion *self,
                                                         RotMatrix m);

Evaluate the 4x4 Matrix corresponding to the 3D rotation.

self :

the quaternion desctibing the rotation

m :

The result will be stored in this matrix.

mia_quaternion_multby ()

MiaQuaternion *     mia_quaternion_multby               (MiaQuaternion *self,
                                                         MiaQuaternion *other);

Multiply the quaternion dest by a quaternion other as in dest *= other

self :

destination quaternion

other :

other quaternion to multiply by

Returns :

the quaternion self

mia_quaternion_new ()

MiaQuaternion *     mia_quaternion_new                  (gfloat x,
                                                         gfloat y,
                                                         gfloat z,
                                                         gfloat w);

Create a quaternion q = w + x *i + y * j + z * k.

x :

x-component of rotation axis

y :

y-component of rotation axis

z :

z-component of rotation axis

w :

scalar part of the quaternion

Returns :

a newly created quaternion representing the rotation

mia_quaternion_new_from_eulerrot ()

MiaQuaternion *     mia_quaternion_new_from_eulerrot    (const MiaVector3d *axis,
                                                         gfloat angle);

Create a quaternion that represents a rotation around the given axis by the given angle. The returned quaternion must be destroyed by calling g_object_unref()

axis :

the rotation axis

angle :

the rotation angle

Returns :

a newly created quaternion

mia_quaternion_norm ()

gfloat              mia_quaternion_norm                 (const MiaQuaternion *self);

Evaluate the quaternions norm.

self :

the quaternion

Returns :

the Euclidian norm

mia_quaternion_normalize ()

void                mia_quaternion_normalize            (MiaQuaternion *self);

Normalize a quaternion if it's norm is not zero.

self :

the quaternion to be normalized

mia_quaternion_test ()

gboolean            mia_quaternion_test                 (void);

Test the quaternion implementation

Returns :

TRUE if all tests pass, FALSE otherwise.

mia_quaternion_xmlio_read ()

void                mia_quaternion_xmlio_read           (ParserState *state,
                                                         const gchar *property);

Helper function to read a quaternion from a XML file

state :

XML parser state holding the parent object and the values

property :

property name the quaternion has in the parent class

mia_quaternion_xmlio_write ()

gboolean            mia_quaternion_xmlio_write          (xmlNodePtr root,
                                                         xmlNsPtr ns,
                                                         const gchar *tag,
                                                         const MiaQuaternion *q);

Helper function to write a quaternion to a XML file

root :

xml node this quaternion will be attached to

ns :

name space

tag :

the xml tag to store this quaternion under

q :

the quaternion

Returns :

true if the node creation was successfu, otherwise false.