mutter/cogl/cogl-quaternion.h

551 lines
15 KiB
C
Raw Normal View History

/*
* Cogl
*
This re-licenses Cogl 1.18 under the MIT license Since the Cogl 1.18 branch is actively maintained in parallel with the master branch; this is a counter part to commit 1b83ef938fc16b which re-licensed the master branch to use the MIT license. This re-licensing is a follow up to the proposal that was sent to the Cogl mailing list: http://lists.freedesktop.org/archives/cogl/2013-December/001465.html Note: there was a copyright assignment policy in place for Clutter (and therefore Cogl which was part of Clutter at the time) until the 11th of June 2010 and so we only checked the details after that point (commit 0bbf50f905) For each file, authors were identified via this Git command: $ git blame -p -C -C -C20 -M -M10 0bbf50f905..HEAD We received blanket approvals for re-licensing all Red Hat and Collabora contributions which reduced how many people needed to be contacted individually: - http://lists.freedesktop.org/archives/cogl/2013-December/001470.html - http://lists.freedesktop.org/archives/cogl/2014-January/001536.html Individual approval requests were sent to all the other identified authors who all confirmed the re-license on the Cogl mailinglist: http://lists.freedesktop.org/archives/cogl/2014-January As well as updating the copyright header in all sources files, the COPYING file has been updated to reflect the license change and also document the other licenses used in Cogl such as the SGI Free Software License B, version 2.0 and the 3-clause BSD license. This patch was not simply cherry-picked from master; but the same methodology was used to check the source files.
2014-02-21 20:28:54 -05:00
* A Low Level GPU Graphics and Utilities API
*
* Copyright (C) 2010 Intel Corporation.
*
This re-licenses Cogl 1.18 under the MIT license Since the Cogl 1.18 branch is actively maintained in parallel with the master branch; this is a counter part to commit 1b83ef938fc16b which re-licensed the master branch to use the MIT license. This re-licensing is a follow up to the proposal that was sent to the Cogl mailing list: http://lists.freedesktop.org/archives/cogl/2013-December/001465.html Note: there was a copyright assignment policy in place for Clutter (and therefore Cogl which was part of Clutter at the time) until the 11th of June 2010 and so we only checked the details after that point (commit 0bbf50f905) For each file, authors were identified via this Git command: $ git blame -p -C -C -C20 -M -M10 0bbf50f905..HEAD We received blanket approvals for re-licensing all Red Hat and Collabora contributions which reduced how many people needed to be contacted individually: - http://lists.freedesktop.org/archives/cogl/2013-December/001470.html - http://lists.freedesktop.org/archives/cogl/2014-January/001536.html Individual approval requests were sent to all the other identified authors who all confirmed the re-license on the Cogl mailinglist: http://lists.freedesktop.org/archives/cogl/2014-January As well as updating the copyright header in all sources files, the COPYING file has been updated to reflect the license change and also document the other licenses used in Cogl such as the SGI Free Software License B, version 2.0 and the 3-clause BSD license. This patch was not simply cherry-picked from master; but the same methodology was used to check the source files.
2014-02-21 20:28:54 -05:00
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
This re-licenses Cogl 1.18 under the MIT license Since the Cogl 1.18 branch is actively maintained in parallel with the master branch; this is a counter part to commit 1b83ef938fc16b which re-licensed the master branch to use the MIT license. This re-licensing is a follow up to the proposal that was sent to the Cogl mailing list: http://lists.freedesktop.org/archives/cogl/2013-December/001465.html Note: there was a copyright assignment policy in place for Clutter (and therefore Cogl which was part of Clutter at the time) until the 11th of June 2010 and so we only checked the details after that point (commit 0bbf50f905) For each file, authors were identified via this Git command: $ git blame -p -C -C -C20 -M -M10 0bbf50f905..HEAD We received blanket approvals for re-licensing all Red Hat and Collabora contributions which reduced how many people needed to be contacted individually: - http://lists.freedesktop.org/archives/cogl/2013-December/001470.html - http://lists.freedesktop.org/archives/cogl/2014-January/001536.html Individual approval requests were sent to all the other identified authors who all confirmed the re-license on the Cogl mailinglist: http://lists.freedesktop.org/archives/cogl/2014-January As well as updating the copyright header in all sources files, the COPYING file has been updated to reflect the license change and also document the other licenses used in Cogl such as the SGI Free Software License B, version 2.0 and the 3-clause BSD license. This patch was not simply cherry-picked from master; but the same methodology was used to check the source files.
2014-02-21 20:28:54 -05:00
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
This re-licenses Cogl 1.18 under the MIT license Since the Cogl 1.18 branch is actively maintained in parallel with the master branch; this is a counter part to commit 1b83ef938fc16b which re-licensed the master branch to use the MIT license. This re-licensing is a follow up to the proposal that was sent to the Cogl mailing list: http://lists.freedesktop.org/archives/cogl/2013-December/001465.html Note: there was a copyright assignment policy in place for Clutter (and therefore Cogl which was part of Clutter at the time) until the 11th of June 2010 and so we only checked the details after that point (commit 0bbf50f905) For each file, authors were identified via this Git command: $ git blame -p -C -C -C20 -M -M10 0bbf50f905..HEAD We received blanket approvals for re-licensing all Red Hat and Collabora contributions which reduced how many people needed to be contacted individually: - http://lists.freedesktop.org/archives/cogl/2013-December/001470.html - http://lists.freedesktop.org/archives/cogl/2014-January/001536.html Individual approval requests were sent to all the other identified authors who all confirmed the re-license on the Cogl mailinglist: http://lists.freedesktop.org/archives/cogl/2014-January As well as updating the copyright header in all sources files, the COPYING file has been updated to reflect the license change and also document the other licenses used in Cogl such as the SGI Free Software License B, version 2.0 and the 3-clause BSD license. This patch was not simply cherry-picked from master; but the same methodology was used to check the source files.
2014-02-21 20:28:54 -05:00
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* Authors:
* Robert Bragg <robert@linux.intel.com>
*/
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_QUATERNION_H__
#define __COGL_QUATERNION_H__
#include <cogl/cogl-types.h>
#include <cogl/cogl-vector.h>
COGL_BEGIN_DECLS
/**
* SECTION:cogl-quaternion
* @short_description: Functions for initializing and manipulating
* quaternions.
*
* Quaternions have become a standard form for representing 3D
* rotations and have some nice properties when compared with other
* representation such as (roll,pitch,yaw) Euler angles. They can be
* used to interpolate between different rotations and they don't
* suffer from a problem called
* <ulink url="http://en.wikipedia.org/wiki/Gimbal_lock">"Gimbal lock"</ulink>
* where two of the axis of rotation may become aligned and you loose a
* degree of freedom.
* .
*/
#include <cogl/cogl-vector.h>
#include <cogl/cogl-euler.h>
/**
* CoglQuaternion:
* @w: based on the angle of rotation it is cos(𝜃/2)
* @x: based on the angle of rotation and x component of the axis of
* rotation it is sin(𝜃/2)*axis.x
* @y: based on the angle of rotation and y component of the axis of
* rotation it is sin(𝜃/2)*axis.y
* @z: based on the angle of rotation and z component of the axis of
* rotation it is sin(𝜃/2)*axis.z
*
* A quaternion is comprised of a scalar component and a 3D vector
* component. The scalar component is normally referred to as w and the
* vector might either be referred to as v or a (for axis) or expanded
* with the individual components: (x, y, z) A full quaternion would
* then be written as <literal>[w (x, y, z)]</literal>.
*
* Quaternions can be considered to represent an axis and angle
* pair although sadly these numbers are buried somewhat under some
* maths...
*
* For the curious you can see here that a given axis (a) and angle (𝜃)
* pair are represented in a quaternion as follows:
* |[
* [w=cos(𝜃/2) ( x=sin(𝜃/2)*a.x, y=sin(𝜃/2)*a.y, z=sin(𝜃/2)*a.x )]
* ]|
*
* Unit Quaternions:
* When using Quaternions to represent spatial orientations for 3D
* graphics it's always assumed you have a unit quaternion. The
* magnitude of a quaternion is defined as:
* |[
* sqrt (w² + x² + y² + z²)
* ]|
* and a unit quaternion satisfies this equation:
* |[
* w² + x² + y² + z² = 1
* ]|
*
* Thankfully most of the time we don't actually have to worry about
* the maths that goes on behind the scenes but if you are curious to
* learn more here are some external references:
*
* <itemizedlist>
* <listitem>
* <ulink url="http://mathworld.wolfram.com/Quaternion.html"/>
* </listitem>
* <listitem>
* <ulink url="http://www.gamedev.net/reference/articles/article1095.asp"/>
* </listitem>
* <listitem>
* <ulink url="http://www.cprogramming.com/tutorial/3d/quaternions.html"/>
* </listitem>
* <listitem>
* <ulink url="http://www.isner.com/tutorials/quatSpells/quaternion_spells_12.htm"/>
* </listitem>
* <listitem>
* 3D Maths Primer for Graphics and Game Development ISBN-10: 1556229119
* </listitem>
* <listitem>
* <ulink url="http://www.cs.caltech.edu/courses/cs171/quatut.pdf"/>
* </listitem>
* <listitem>
* <ulink url="http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q56"/>
* </listitem>
* </itemizedlist>
*
*/
struct _CoglQuaternion
{
float w;
float x;
float y;
float z;
/*< private >*/
float padding0;
float padding1;
float padding2;
float padding3;
};
COGL_STRUCT_SIZE_ASSERT (CoglQuaternion, 32);
/**
* cogl_quaternion_init:
* @quaternion: An uninitialized #CoglQuaternion
* @angle: The angle you want to rotate around the given axis
* @x: The x component of your axis vector about which you want to
* rotate.
* @y: The y component of your axis vector about which you want to
* rotate.
* @z: The z component of your axis vector about which you want to
* rotate.
*
* Initializes a quaternion that rotates @angle degrees around the
* axis vector (@x, @y, @z). The axis vector does not need to be
* normalized.
*
* Returns: A normalized, unit quaternion representing an orientation
* rotated @angle degrees around the axis vector (@x, @y, @z)
*
* Since: 2.0
*/
void
cogl_quaternion_init (CoglQuaternion *quaternion,
float angle,
float x,
float y,
float z);
/**
* cogl_quaternion_init_from_angle_vector:
* @quaternion: An uninitialized #CoglQuaternion
* @angle: The angle to rotate around @axis3f
* @axis3f: your 3 component axis vector about which you want to rotate.
*
* Initializes a quaternion that rotates @angle degrees around the
* given @axis vector. The axis vector does not need to be
* normalized.
*
* Returns: A normalized, unit quaternion representing an orientation
* rotated @angle degrees around the given @axis vector.
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_angle_vector (CoglQuaternion *quaternion,
float angle,
const float *axis3f);
/**
* cogl_quaternion_init_identity:
* @quaternion: An uninitialized #CoglQuaternion
*
* Initializes the quaternion with the canonical quaternion identity
* [1 (0, 0, 0)] which represents no rotation. Multiplying a
* quaternion with this identity leaves the quaternion unchanged.
*
* You might also want to consider using
* cogl_get_static_identity_quaternion().
*
* Since: 2.0
*/
void
cogl_quaternion_init_identity (CoglQuaternion *quaternion);
/**
* cogl_quaternion_init_from_array:
* @quaternion: A #CoglQuaternion
* @array: An array of 4 floats w,(x,y,z)
*
* Initializes a [w (x, y,z)] quaternion directly from an array of 4
* floats: [w,x,y,z].
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_array (CoglQuaternion *quaternion,
const float *array);
/**
* cogl_quaternion_init_from_x_rotation:
* @quaternion: An uninitialized #CoglQuaternion
* @angle: The angle to rotate around the x axis
*
* XXX: check which direction this rotates
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_x_rotation (CoglQuaternion *quaternion,
float angle);
/**
* cogl_quaternion_init_from_y_rotation:
* @quaternion: An uninitialized #CoglQuaternion
* @angle: The angle to rotate around the y axis
*
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_y_rotation (CoglQuaternion *quaternion,
float angle);
/**
* cogl_quaternion_init_from_z_rotation:
* @quaternion: An uninitialized #CoglQuaternion
* @angle: The angle to rotate around the z axis
*
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_z_rotation (CoglQuaternion *quaternion,
float angle);
/**
* cogl_quaternion_init_from_euler:
* @quaternion: A #CoglQuaternion
* @euler: A #CoglEuler with which to initialize the quaternion
*
* Since: 2.0
*/
void
cogl_quaternion_init_from_euler (CoglQuaternion *quaternion,
const CoglEuler *euler);
/**
* cogl_quaternion_init_from_quaternion:
* @quaternion: A #CoglQuaternion
* @src: A #CoglQuaternion with which to initialize @quaternion
*
* Since: 2.0
*/
Add -Wmissing-declarations to maintainer flags and fix problems This option to GCC makes it give a warning whenever a global function is defined without a declaration. This should catch cases were we've defined a function but forgot to put it in a header. In that case it is either only used within one file so we should make it static or we should declare it in a header. The following changes where made to fix problems: • Some functions were made static • cogl-path.h (the one containing the 1.0 API) was split into two files, one defining the functions and one defining the enums so that cogl-path.c can include the enum and function declarations from the 2.0 API as well as the function declarations from the 1.0 API. • cogl2-clip-state has been removed. This only had one experimental function called cogl_clip_push_from_path but as this is unstable we might as well remove it favour of the equivalent cogl_framebuffer_* API. • The GLX, SDL and WGL winsys's now have a private header to define their get_vtable function instead of directly declaring in the C file where it is called. • All places that were calling COGL_OBJECT_DEFINE need to have the cogl_is_whatever function declared so these have been added either as a public function or in a private header. • Some files that were not including the header containing their function declarations have been fixed to do so. • Any unused error quark functions have been removed. If we later want them we should add them back one by one and add a declaration for them in a header. • _cogl_is_framebuffer has been renamed to cogl_is_framebuffer and made a public function with a declaration in cogl-framebuffer.h • Similarly for CoglOnscreen. • cogl_vdraw_indexed_attributes is called cogl_framebuffer_vdraw_indexed_attributes in the header. The definition has been changed to match the header. • cogl_index_buffer_allocate has been removed. This had no declaration and I'm not sure what it's supposed to do. • CoglJournal has been changed to use the internal CoglObject macro so that it won't define an exported cogl_is_journal symbol. • The _cogl_blah_pointer_from_handle functions have been removed. CoglHandle isn't used much anymore anyway and in the few places where it is used I think it's safe to just use the implicit cast from void* to the right type. • The test-utils.h header for the conformance tests explicitly disables the -Wmissing-declaration option using a pragma because all of the tests declare their main function without a header. Any mistakes relating to missing declarations aren't really important for the tests. • cogl_quaternion_init_from_quaternion and init_from_matrix have been given declarations in cogl-quaternion.h Reviewed-by: Robert Bragg <robert@linux.intel.com>
2012-03-06 13:21:28 -05:00
void
cogl_quaternion_init_from_quaternion (CoglQuaternion *quaternion,
CoglQuaternion *src);
/**
* cogl_quaternion_init_from_matrix:
* @quaternion: A Cogl Quaternion
* @matrix: A rotation matrix with which to initialize the quaternion
*
* Initializes a quaternion from a rotation matrix.
*
* Since: 1.10
* Stability: unstable
*/
void
cogl_quaternion_init_from_matrix (CoglQuaternion *quaternion,
const CoglMatrix *matrix);
/**
* cogl_quaternion_equal:
* @v1: A #CoglQuaternion
* @v2: A #CoglQuaternion
*
* Compares that all the components of quaternions @a and @b are
* equal.
*
* An epsilon value is not used to compare the float components, but
* the == operator is at least used so that 0 and -0 are considered
* equal.
*
* Returns: %TRUE if the quaternions are equal else %FALSE.
*
* Since: 2.0
*/
CoglBool
cogl_quaternion_equal (const void *v1, const void *v2);
/**
* cogl_quaternion_copy:
* @src: A #CoglQuaternion
*
* Allocates a new #CoglQuaternion on the stack and initializes it with
* the same values as @src.
*
* Returns: A newly allocated #CoglQuaternion which should be freed
* using cogl_quaternion_free()
*
* Since: 2.0
*/
CoglQuaternion *
cogl_quaternion_copy (const CoglQuaternion *src);
/**
* cogl_quaternion_free:
* @quaternion: A #CoglQuaternion
*
* Frees a #CoglQuaternion that was previously allocated via
* cogl_quaternion_copy().
*
* Since: 2.0
*/
void
cogl_quaternion_free (CoglQuaternion *quaternion);
/**
* cogl_quaternion_get_rotation_angle:
* @quaternion: A #CoglQuaternion
*
*
* Since: 2.0
*/
float
cogl_quaternion_get_rotation_angle (const CoglQuaternion *quaternion);
/**
* cogl_quaternion_get_rotation_axis:
* @quaternion: A #CoglQuaternion
* @vector3: (out): an allocated 3-float array
*
* Since: 2.0
*/
void
cogl_quaternion_get_rotation_axis (const CoglQuaternion *quaternion,
float *vector3);
/**
* cogl_quaternion_normalize:
* @quaternion: A #CoglQuaternion
*
*
* Since: 2.0
*/
void
cogl_quaternion_normalize (CoglQuaternion *quaternion);
/**
* cogl_quaternion_dot_product:
* @a: A #CoglQuaternion
* @b: A #CoglQuaternion
*
* Since: 2.0
*/
float
cogl_quaternion_dot_product (const CoglQuaternion *a,
const CoglQuaternion *b);
/**
* cogl_quaternion_invert:
* @quaternion: A #CoglQuaternion
*
*
* Since: 2.0
*/
void
cogl_quaternion_invert (CoglQuaternion *quaternion);
/**
* cogl_quaternion_multiply:
* @result: The destination #CoglQuaternion
* @left: The second #CoglQuaternion rotation to apply
* @right: The first #CoglQuaternion rotation to apply
*
* This combines the rotations of two quaternions into @result. The
* operation is not commutative so the order is important because AxB
* != BxA. Cogl follows the standard convention for quaternions here
* so the rotations are applied @right to @left. This is similar to the
* combining of matrices.
*
* <note>It is possible to multiply the @a quaternion in-place, so
* @result can be equal to @a but can't be equal to @b.</note>
*
* Since: 2.0
*/
void
cogl_quaternion_multiply (CoglQuaternion *result,
const CoglQuaternion *left,
const CoglQuaternion *right);
/**
* cogl_quaternion_pow:
* @quaternion: A #CoglQuaternion
* @exponent: the exponent
*
*
* Since: 2.0
*/
void
cogl_quaternion_pow (CoglQuaternion *quaternion, float exponent);
/**
* cogl_quaternion_slerp:
* @result: The destination #CoglQuaternion
* @a: The first #CoglQuaternion
* @b: The second #CoglQuaternion
* @t: The factor in the range [0,1] used to interpolate between
* quaternion @a and @b.
*
* Performs a spherical linear interpolation between two quaternions.
*
* Noteable properties:
* <itemizedlist>
* <listitem>
* commutative: No
* </listitem>
* <listitem>
* constant velocity: Yes
* </listitem>
* <listitem>
* torque minimal (travels along the surface of the 4-sphere): Yes
* </listitem>
* <listitem>
* more expensive than cogl_quaternion_nlerp()
* </listitem>
* </itemizedlist>
*/
void
cogl_quaternion_slerp (CoglQuaternion *result,
const CoglQuaternion *a,
const CoglQuaternion *b,
float t);
/**
* cogl_quaternion_nlerp:
* @result: The destination #CoglQuaternion
* @a: The first #CoglQuaternion
* @b: The second #CoglQuaternion
* @t: The factor in the range [0,1] used to interpolate between
* quaterion @a and @b.
*
* Performs a normalized linear interpolation between two quaternions.
* That is it does a linear interpolation of the quaternion components
* and then normalizes the result. This will follow the shortest arc
* between the two orientations (just like the slerp() function) but
* will not progress at a constant speed. Unlike slerp() nlerp is
* commutative which is useful if you are blending animations
* together. (I.e. nlerp (tmp, a, b) followed by nlerp (result, tmp,
* d) is the same as nlerp (tmp, a, d) followed by nlerp (result, tmp,
* b)). Finally nlerp is cheaper than slerp so it can be a good choice
* if you don't need the constant speed property of the slerp() function.
*
* Notable properties:
* <itemizedlist>
* <listitem>
* commutative: Yes
* </listitem>
* <listitem>
* constant velocity: No
* </listitem>
* <listitem>
* torque minimal (travels along the surface of the 4-sphere): Yes
* </listitem>
* <listitem>
* faster than cogl_quaternion_slerp()
* </listitem>
* </itemizedlist>
*/
void
cogl_quaternion_nlerp (CoglQuaternion *result,
const CoglQuaternion *a,
const CoglQuaternion *b,
float t);
/**
* cogl_quaternion_squad:
* @result: The destination #CoglQuaternion
* @prev: A #CoglQuaternion used before @a
* @a: The first #CoglQuaternion
* @b: The second #CoglQuaternion
* @next: A #CoglQuaternion that will be used after @b
* @t: The factor in the range [0,1] used to interpolate between
* quaternion @a and @b.
*
*
* Since: 2.0
*/
void
cogl_quaternion_squad (CoglQuaternion *result,
const CoglQuaternion *prev,
const CoglQuaternion *a,
const CoglQuaternion *b,
const CoglQuaternion *next,
float t);
/**
* cogl_get_static_identity_quaternion:
*
* Returns a pointer to a singleton quaternion constant describing the
* canonical identity [1 (0, 0, 0)] which represents no rotation.
*
* If you multiply a quaternion with the identity quaternion you will
* get back the same value as the original quaternion.
*
* Returns: A pointer to an identity quaternion
*
* Since: 2.0
*/
const CoglQuaternion *
cogl_get_static_identity_quaternion (void);
/**
* cogl_get_static_zero_quaternion:
*
* Returns: a pointer to a singleton quaternion constant describing a
* rotation of 180 degrees around a degenerate axis:
* [0 (0, 0, 0)]
*
* Since: 2.0
*/
const CoglQuaternion *
cogl_get_static_zero_quaternion (void);
COGL_END_DECLS
#endif /* __COGL_QUATERNION_H__ */