Quaternion routines

There is a special set of functions and macros to handle quaternions. A Gan_Quaternion is basically the same object as a Gan_Vector4, and a lot of the routines are macro calls to the equivalent 4-vector routines. Here is a code fragment illustrating the use of quaternions in Gandalf.

      Gan_Quaternion q1, q2, q3; /* declare three quaternions */

      /* fill q1 the "quick" way and scale it to unit length */
      gan_quat_fill_q ( &q1, 0.5, -0.2, 0.3, 0.3 );
      gan_quat_unit_i ( &q1 );

      /* fill q2 the "slow" way and scale it to unit length */
      q2 = gan_quat_fill_s ( -0.4, 0.7, 0.1, 0.9 );
      q2 = gan_quat_unit_s ( &q2 );

      /* add two quaternions */
      gan_quat_add_q ( &q1, &q2, &q3 );

      /* subtract two quaternions */
      gan_quat_sub_q ( &q1, &q2, &q3 );

      /* multiply a quaternion by a scalar */
      gan_quat_scale_q ( &q1, 2.0, &q3 ); /* q3 = 2*q1, OR */
      q3 = gan_quat_scale_s ( &q1, 2.0 ); /* q3 = 2*q1, OR */
      gan_quat_scale_i ( &q1, 2.0 ); /* replace q1 = 2*q1 in-place */

      /* divide a quaternion by a scalar */
      gan_quat_divide_q ( &q1, 2.0, &q3 ); /* q3 = q1/2, OR */
      q3 = gan_quat_divide_s ( &q1, 2.0 ); /* q3 = q1/2, OR */
      gan_quat_divide_i ( &q1, 2.0 ); /* replace q1 = q1/2 in-place */

      /* print squared length of quaternion */
      printf ( "quaternion squared length |q|^2=%f\n",
               gan_quat_sqrlen_q(&q3) ); /* macro version, OR */
      printf ( "quaternion squared length |q|^2=%f\n",
               gan_quat_sqrlen_s(&q3) ); /* function version */

Error detection: The routines gan_quat_divide_[qi]() and gan_quat_unit_[qi]() return NULL upon division by zero error, invoking the Gandalf error handler, whereas the equivalent ..._s() routines abort the program on error.