cogl/cogl-euler.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2010 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  *
  23  * Authors:
  24  *   Robert Bragg <robert@linux.intel.com>
  25  */
  26
  27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  28 #error "Only <cogl/cogl.h> can be included directly."
  29 #endif
  30
  31 #ifndef __COGL_EULER_H
  32 #define __COGL_EULER_H
  33
  34 #include <cogl/cogl-types.h>
  35
  36 #include <glib.h>
  37
  38 G_BEGIN_DECLS
  39
  40 /**
  41  * SECTION:cogl-euler
  42  * @short_description: Functions for initializing and manipulating
  43  * euler angles.
  44  *
  45  * Euler angles are a simple representation of a 3 dimensional
  46  * rotation; comprised of 3 ordered heading, pitch and roll rotations.
  47  * An important thing to understand is that the axis of rotation
  48  * belong to the object being rotated and so they also rotate as each
  49  * of the heading, pitch and roll rotations are applied.
  50  *
  51  * One way to consider euler angles is to imagine controlling an
  52  * aeroplane, where you first choose a heading (Such as flying south
  53  * east), then you set the pitch (such as 30 degrees to take off) and
  54  * then you might set a roll, by dipping the left, wing as you prepare
  55  * to turn.
  56  *
  57  * They have some advantages and limitations that it helps to be
  58  * aware of:
  59  *
  60  * Advantages:
  61  * <itemizedlist>
  62  * <listitem>
  63  * Easy to understand and use, compared to quaternions and matrices,
  64  * so may be a good choice for a user interface.
  65  * <listitem>
  66  * <listitem>
  67  * Efficient storage, needing only 3 components any rotation can be
  68  * represented.
  69  * <note>Actually the #CoglEuler type isn't optimized for size because
  70  * we may cache the equivalent #CoglQuaternion along with a euler
  71  * rotation, but it would be trivial for an application to track the
  72  * components of euler rotations in a packed float array if optimizing
  73  * for size was important. The values could be passed to Cogl only when
  74  * manipulation is necessary.</note>
  75  * </listitem>
  76  * </itemizedlist>
  77  *
  78  * Disadvantages:
  79  * <itemizedlist>
  80  * <listitem>
  81  * Aliasing: it's possible to represent some rotations with multiple
  82  * different heading, pitch and roll rotations.
  83  * </listitem>
  84  * <listitem>
  85  * They can suffer from a problem called Gimbal Lock. A good
  86  * explanation of this can be seen on wikipedia here:
  87  * http://en.wikipedia.org/wiki/Gimbal_lock but basically two
  88  * of the axis of rotation may become aligned and so you loose a
  89  * degree of freedom. For example a pitch of +-90° would mean that
  90  * heading and bank rotate around the same axis.
  91  * </listitem>
  92  * <listitem>
  93  * If you use euler angles to orient something in 3D space and try to
  94  * transition between orientations by interpolating the component
  95  * angles you probably wont get the transitions you expect as they may
  96  * not follow the shortest path between the two orientations.
  97  * </listitem>
  98  * <listitem>
  99  * There's no standard to what order the component axis rotations are
 100  * applied. The most common convention seems to be what we do in Cogl
 101  * with heading (y-axis), pitch (x-axis) and then roll (z-axis), but
 102  * other software might apply x-axis, y-axis then z-axis or any other
 103  * order so you need to consider this if you are accepting euler
 104  * rotations from some other software. Other software may also use
 105  * slightly different aeronautical terms, such as "yaw" instead of
 106  * "heading" or "bank" instead of "roll".
 107  * </listitem>
 108  * </itemlist>
 109  *
 110  * To minimize the aliasing issue we may refer to "Canonical Euler"
 111  * angles where heading and roll are restricted to +- 180° and pitch is
 112  * restricted to +- 90°. If pitch is +- 90° bank is set to 0°.
 113  *
 114  * Quaternions don't suffer from Gimbal Lock and they can be nicely
 115  * interpolated between, their disadvantage is that they don't have an
 116  * intuitive representation.
 117  *
 118  * A common practice is to accept angles in the intuitive Euler form
 119  * and convert them to quaternions internally to avoid Gimbal Lock and
 120  * handle interpolations. See cogl_quaternion_init_from_euler().
 121  */
 122
 123 /**
 124  * CoglEuler:
 125  * @heading: Angle to rotate around an object's y axis
 126  * @pitch: Angle to rotate around an object's x axis
 127  * @roll: Angle to rotate around an object's z axis
 128  *
 129  * Represents an ordered rotation first of @heading degrees around an
 130  * object's y axis, then @pitch degrees around an object's x axis and
 131  * finally @roll degrees around an object's z axis.
 132  *
 133  * <note>It's important to understand the that axis are associated
 134  * with the object being rotated, so the axis also rotate in sequence
 135  * with the rotations being applied.</note>
 136  *
 137  * The members of a #CoglEuler can be initialized, for example, with
 138  * cogl_euler_init() and cogl_euler_init_from_quaternion ().
 139  *
 140  * You may also want to look at cogl_quaternion_init_from_euler() if
 141  * you want to do interpolation between 3d rotations.
 142  *
 143  * Since: 2.0
 144  */
 145 struct _CoglEuler
 146 {
 147   /*< public > */
 148   float heading;
 149   float pitch;
 150   float roll;
 151
 152   /*< private > */
 153   /* May cached a quaternion here in the future */
 154   float padding0;
 155   float padding1;
 156   float padding2;
 157   float padding3;
 158   float padding4;
 159 };
 160 COGL_STRUCT_SIZE_ASSERT (CoglEuler, 32);
 161
 162 /**
 163  * cogl_euler_init:
 164  * @euler: The #CoglEuler angle to initialize
 165  * @heading: Angle to rotate around an object's y axis
 166  * @pitch: Angle to rotate around an object's x axis
 167  * @roll: Angle to rotate around an object's z axis
 168  *
 169  * Initializes @euler to represent a rotation of @x_angle degrees
 170  * around the x axis, then @y_angle degrees around the y_axis and
 171  * @z_angle degrees around the z axis.
 172  *
 173  * Since: 2.0
 174  */
 175 void
 176 cogl_euler_init (CoglEuler *euler,
 177                  float heading,
 178                  float pitch,
 179                  float roll);
 180
 181 /**
 182  * cogl_euler_init_from_matrix:
 183  * @euler: The #CoglEuler angle to initialize
 184  * @matrix: A #CoglMatrix containing a rotation, but no scaling,
 185  *          mirroring or skewing.
 186  *
 187  * Extracts a euler rotation from the given @matrix and
 188  * initializses @euler with the component x, y and z rotation angles.
 189  */
 190 void
 191 cogl_euler_init_from_matrix (CoglEuler *euler,
 192                              const CoglMatrix *matrix);
 193
 194 /**
 195  * cogl_euler_init_from_quaternion:
 196  * @euler: The #CoglEuler angle to initialize
 197  * @quaternion: A #CoglEuler with the rotation to initialize with
 198  *
 199  * Initializes a @euler rotation with the equivalent rotation
 200  * represented by the given @quaternion.
 201  */
 202 void
 203 cogl_euler_init_from_quaternion (CoglEuler *euler,
 204                                  const CoglQuaternion *quaternion);
 205
 206 /**
 207  * cogl_euler_equal:
 208  * @v1: The first euler angle to compare
 209  * @v1: The second euler angle to compare
 210  *
 211  * Compares the two given euler angles @v1 and @v1 and it they are
 212  * equal returns %TRUE else %FALSE.
 213  *
 214  * <note>This function only checks that all three components rotations
 215  * are numerically equal, it does not consider that some rotations
 216  * can be represented with different component rotations</note>
 217  *
 218  * Returns: %TRUE if @v1 and @v2 are equal else %FALSE.
 219  * Since: 2.0
 220  */
 221 gboolean
 222 cogl_euler_equal (gconstpointer v1, gconstpointer v2);
 223
 224 /**
 225  * cogl_euler_copy:
 226  * @src: A #CoglEuler to copy
 227  *
 228  * Allocates a new #CoglEuler and initilizes it with the component
 229  * angles of @src. The newly allocated euler should be freed using
 230  * cogl_euler_free().
 231  *
 232  * Returns: A newly allocated #CoglEuler
 233  * Since: 2.0
 234  */
 235 CoglEuler *
 236 cogl_euler_copy (const CoglEuler *src);
 237
 238 /**
 239  * cogl_euler_free:
 240  * @euler: A #CoglEuler allocated via cogl_euler_copy()
 241  *
 242  * Frees a #CoglEuler that was previously allocated using
 243  * cogl_euler_copy().
 244  *
 245  * Since: 2.0
 246  */
 247 void
 248 cogl_euler_free (CoglEuler *euler);
 249
 250 G_END_DECLS
 251
 252 #endif /* __COGL_EULER_H */
 253