Top 
Functions
void  cogl_euler_init () 
void  cogl_euler_init_from_matrix () 
void  cogl_euler_init_from_quaternion () 
CoglBool  cogl_euler_equal () 
CoglEuler *  cogl_euler_copy () 
void  cogl_euler_free () 
Description
Euler angles are a simple representation of a 3 dimensional rotation; comprised of 3 ordered heading, pitch and roll rotations. An important thing to understand is that the axis of rotation belong to the object being rotated and so they also rotate as each of the heading, pitch and roll rotations are applied.
One way to consider euler angles is to imagine controlling an aeroplane, where you first choose a heading (Such as flying south east), then you set the pitch (such as 30 degrees to take off) and then you might set a roll, by dipping the left, wing as you prepare to turn.
They have some advantages and limitations that it helps to be aware of:
Advantages:
 Easy to understand and use, compared to quaternions and matrices, so may be a good choice for a user interface.

Efficient storage, needing only 3 components any rotation can be
represented.
Actually the CoglEuler type isn't optimized for size because we may cache the equivalent CoglQuaternion along with a euler rotation, but it would be trivial for an application to track the components of euler rotations in a packed float array if optimizing for size was important. The values could be passed to Cogl only when manipulation is necessary.
Disadvantages:
 Aliasing: it's possible to represent some rotations with multiple different heading, pitch and roll rotations.
 They can suffer from a problem called Gimbal Lock. A good explanation of this can be seen on wikipedia here: http://en.wikipedia.org/wiki/Gimbal_lock but basically two of the axis of rotation may become aligned and so you loose a degree of freedom. For example a pitch of +90° would mean that heading and bank rotate around the same axis.
 If you use euler angles to orient something in 3D space and try to transition between orientations by interpolating the component angles you probably wont get the transitions you expect as they may not follow the shortest path between the two orientations.
 There's no standard to what order the component axis rotations are applied. The most common convention seems to be what we do in Cogl with heading (yaxis), pitch (xaxis) and then roll (zaxis), but other software might apply xaxis, yaxis then zaxis or any other order so you need to consider this if you are accepting euler rotations from some other software. Other software may also use slightly different aeronautical terms, such as "yaw" instead of "heading" or "bank" instead of "roll".
To minimize the aliasing issue we may refer to "Canonical Euler" angles where heading and roll are restricted to + 180° and pitch is restricted to + 90°. If pitch is + 90° bank is set to 0°.
Quaternions don't suffer from Gimbal Lock and they can be nicely interpolated between, their disadvantage is that they don't have an intuitive representation.
A common practice is to accept angles in the intuitive Euler form
and convert them to quaternions internally to avoid Gimbal Lock and
handle interpolations. See cogl_quaternion_init_from_euler()
.
Functions
cogl_euler_init ()
void cogl_euler_init (CoglEuler *euler
,float heading
,float pitch
,float roll
);
Initializes euler
to represent a rotation of x_angle
degrees
around the x axis, then y_angle
degrees around the y_axis and
z_angle
degrees around the z axis.
Parameters
euler 
The CoglEuler angle to initialize 

heading 
Angle to rotate around an object's y axis 

pitch 
Angle to rotate around an object's x axis 

roll 
Angle to rotate around an object's z axis 
Since: 2.0
cogl_euler_init_from_matrix ()
void cogl_euler_init_from_matrix (CoglEuler *euler
,const CoglMatrix *matrix
);
Extracts a euler rotation from the given matrix
and
initializses euler
with the component x, y and z rotation angles.
Parameters
euler 
The CoglEuler angle to initialize 

matrix 
A CoglMatrix containing a rotation, but no scaling, mirroring or skewing. 
cogl_euler_init_from_quaternion ()
void cogl_euler_init_from_quaternion (CoglEuler *euler
,const CoglQuaternion *quaternion
);
Initializes a euler
rotation with the equivalent rotation
represented by the given quaternion
.
cogl_euler_equal ()
CoglBool cogl_euler_equal (const void *v1
,const void *v2
);
Compares the two given euler angles v1
and v1
and it they are
equal returns TRUE
else FALSE
.
Since: 2.0
cogl_euler_copy ()
CoglEuler *
cogl_euler_copy (const CoglEuler *src
);
Allocates a new CoglEuler and initilizes it with the component
angles of src
. The newly allocated euler should be freed using
cogl_euler_free()
.
Since: 2.0
cogl_euler_free ()
void
cogl_euler_free (CoglEuler *euler
);
Frees a CoglEuler that was previously allocated using
cogl_euler_copy()
.
Since: 2.0
Types and Values
CoglEuler
typedef struct { float heading; float pitch; float roll; } CoglEuler;
Represents an ordered rotation first of heading
degrees around an
object's y axis, then pitch
degrees around an object's x axis and
finally roll
degrees around an object's z axis.
The members of a CoglEuler can be initialized, for example, with
cogl_euler_init()
and cogl_euler_init_from_quaternion()
.
You may also want to look at cogl_quaternion_init_from_euler()
if
you want to do interpolation between 3d rotations.
Since: 2.0