## quat

quat — quaternion helpers

## Synopsis

    #include <g3d/quat.h>

    typedef             G3DQuat;
    gboolean            g3d_quat_add                        (G3DQuat *qr,
                                                             G3DQuat *q1,
                                                             G3DQuat *q2);
    gboolean            g3d_quat_normalize                  (G3DQuat *q);
    gboolean            g3d_quat_rotate                     (G3DQuat *q,
                                                             G3DVector *axis,
                                                             G3DFloat angle);
    gboolean            g3d_quat_to_matrix                  (G3DQuat *q,
                                                             G3DMatrix *matrix);
    gboolean            g3d_quat_to_rotation_xyz            (G3DQuat *q,
                                                             G3DFloat *rx,
                                                             G3DFloat *ry,
                                                             G3DFloat *rz);
    gboolean            g3d_quat_trackball                  (G3DQuat *q,
                                                             G3DFloat x1,
                                                             G3DFloat y1,
                                                             G3DFloat x2,
                                                             G3DFloat y2,
                                                             G3DFloat r);

## Description

## Details

### G3DQuat

    typedef G3DFloat G3DQuat;

Quaternion element type.

### g3d_quat_add ()

    gboolean            g3d_quat_add                        (G3DQuat *qr,
                                                             G3DQuat *q1,
                                                             G3DQuat *q2);

Add two quats.

`qr` : | result quat
`q1` : | first quat
`q2` : | second quat
Returns : | TRUE on success, FALSE else

### g3d_quat_normalize ()

    gboolean            g3d_quat_normalize                  (G3DQuat *q);

normalize the quaternion to a length of 1.0.

`q` : | a quaternion
Returns : | TRUE on success, FALSE else

### g3d_quat_rotate ()

    gboolean            g3d_quat_rotate                     (G3DQuat *q,
                                                             G3DVector *axis,
                                                             G3DFloat angle);

Encode a rotation around an axis into quaternion.

`q` : | resulting quat
`axis` : | rotation axis
`angle` : | rotation angle
Returns : | TRUE on success, FALSE else

### g3d_quat_to_matrix ()

    gboolean            g3d_quat_to_matrix                  (G3DQuat *q,
                                                             G3DMatrix *matrix);

Convert a quaternion to a transformation matrix.

`q` : | source quat
`matrix` : | resulting matrix
Returns : | TRUE on success, FALSE else

### g3d_quat_to_rotation_xyz ()

    gboolean            g3d_quat_to_rotation_xyz            (G3DQuat *q,
                                                             G3DFloat *rx,
                                                             G3DFloat *ry,
                                                             G3DFloat *rz);

Calculate the rotation around the three coordinate axes from a given quaternion.

`q` : | a quaternion
`rx` : | rotation around x axis
`ry` : | rotation around y axis
`rz` : | rotation around z axis
Returns : | TRUE on success, FALSE else

### g3d_quat_trackball ()

    gboolean            g3d_quat_trackball                  (G3DQuat *q,
                                                             G3DFloat x1,
                                                             G3DFloat y1,
                                                             G3DFloat x2,
                                                             G3DFloat y2,
                                                             G3DFloat r);

Emulate a virtual trackball movement and return rotation as quaternion. The x and y values of the starting and end point of the movement have to be in the range -1.0 .. 1.0.

`q` : | resulting quaternion
`x1` : | x value of first point
`y1` : | y value of first point
`x2` : | x value of second point
`y2` : | y value of second point
`r` : | radius of virtual trackball, usually 0.8
Returns : | TRUE on success, FALSE else