EPhysics Quaternion
EPhysics

Quaternions are used to perform linear algebra rotations. More...

## Data Structures

struct | _EPhysics_Quaternion
| Quaternion coordinates and rotation (w, x, y, z). More...

## Typedefs

typedef struct _EPhysics_Quaternion | EPhysics_Quaternion
| Quaternion handle, represents a quaternion to be used to rotate bodies.

## Functions

EAPI EPhysics_Quaternion * | ephysics_quaternion_new (void)
| Create a new quaternion.
EAPI void | ephysics_quaternion_get (const EPhysics_Quaternion *quat, double *x, double *y, double *z, double *w)
| Get quaternion values.
EAPI void | ephysics_quaternion_axis_angle_get (const EPhysics_Quaternion *quat, double *nx, double *ny, double *nz, double *a)
| Get quaternion axis and angle.
EAPI void | ephysics_quaternion_set (EPhysics_Quaternion *quat, double x, double y, double z, double w)
| Set quaternion values.
EAPI void | ephysics_quaternion_axis_angle_set (EPhysics_Quaternion *quat, double nx, double ny, double nz, double a)
| Set quaternion using axis angle notation.
EAPI void | ephysics_quaternion_euler_set (EPhysics_Quaternion *quat, double yaw, double pitch, double roll)
| Set quaternion using Euler angles.
EAPI void | ephysics_quaternion_normalize (EPhysics_Quaternion *quat)
| Normalize the quaternion.
EAPI void | ephysics_quaternion_invert (EPhysics_Quaternion *quat)
| Invert the quaternion.
EAPI void | ephysics_quaternion_scale (EPhysics_Quaternion *quat, double scale)
| Scale the quaternion.
EAPI void | ephysics_quaternion_inverse_scale (EPhysics_Quaternion *quat, double scale)
| Inversely scale the quaternion.
EAPI EPhysics_Quaternion * | ephysics_quaternion_sum (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2, EPhysics_Quaternion *result)
| Returns a sum of two quaternions.
EAPI EPhysics_Quaternion * | ephysics_quaternion_diff (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2, EPhysics_Quaternion *result)
| Returns a difference between two quaternions.
EAPI EPhysics_Quaternion * | ephysics_quaternion_multiply (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2, EPhysics_Quaternion *result)
| Multiply two quaternions.
EAPI EPhysics_Quaternion * | ephysics_quaternion_slerp (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2, double ratio, EPhysics_Quaternion *result)
| Return the quaternion which is the result of Spherical Linear Interpolation between two quaternions.
EAPI double | ephysics_quaternion_dot (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2)
| Return the dot product between two quaternions.
EAPI double | ephysics_quaternion_angle_get (const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2)
| Return the angle between two quaternions.
EAPI double | ephysics_quaternion_length_get (const EPhysics_Quaternion *quat)
| Return the length of the quaternion.
EAPI double | ephysics_quaternion_length2_get (const EPhysics_Quaternion *quat)
| Return the length squared of the quaternion.

## Detailed Description

Quaternions are used to perform linear algebra rotations.

Functions regarding rotation, like ephysics_body_rotation_set() and ephysics_body_rotation_get() would need that. Quaternions can be used to rotate evas maps as well, with evas_map_util_quat_rotate(), but in this case quaternion values need to be get with ephysics_quaternion_get(), since evas don't accept EPhysics_Quaternion type.

A quaternion can be created with ephysics_quaternion_new(), and many operations can be performed with that, as:

- Sum: ephysics_quaternion_sum()
- Difference: ephysics_quaternion_diff()
- Multiple by another quaternion: ephysics_quaternion_multiply()
- Multiply by scalar: ephysics_quaternion_scale()
- Divide by scalar: ephysics_quaternion_inverse_scale()
- Calculate length: ephysics_quaternion_length_get()
- Calculate angle between quaternions: ephysics_quaternion_angle_get()

## Typedef Documentation

## EPhysics_Quaternion

typedef struct _EPhysics_Quaternion EPhysics_Quaternion

Quaternion handle, represents a quaternion to be used to rotate bodies.

Created with ephysics_quaternion_new() and deleted with free().

Examples
  test_rotating_forever.c.

## Function Documentation

## ephysics_quaternion_new()

EAPI EPhysics_Quaternion * ephysics_quaternion_new | ( | void |  | ) |

Create a new quaternion.

By default a quaternion is created as identity (w = 1, x = 0, y = 0, z = 0). This values can be modified later by quaternion operations or set directly.

Returns
  The created quaternion or `NULL` on error.

Note
  It should be deleted with free() after usage is concluded.

See also
  ephysics_quaternion_set();
  ephysics_quaternion_axis_angle_set();
  ephysics_quaternion_euler_set();
  ephysics_quaternion_scale();
  ephysics_quaternion_sum();

## ephysics_quaternion_get()

EAPI void ephysics_quaternion_get | ( | const EPhysics_Quaternion * | quat,
|  | double * | x,
|  | double * | y,
|  | double * | z,
|  | double * | w )

Get quaternion values.

Parameters

  quat | Quaternion to get values from.
  x | The x coordinate.
  y | The y coordinate.
  z | The z coordinate.
  w | The rotation.

See also
  ephysics_quaternion_set();

Examples
  test_rotating_forever.c.

## ephysics_quaternion_axis_angle_get()

EAPI void ephysics_quaternion_axis_angle_get | ( | const EPhysics_Quaternion * | quat,
|  | double * | nx,
|  | double * | ny,
|  | double * | nz,
|  | double * | a )

Get quaternion axis and angle.

Parameters

  quat | Quaternion to get values from.
  nx | The x component of the axis of rotation.
  ny | The y component of the axis of rotation.
  nz | The z component of the axis of rotation.
  a | The angle of rotation.

See also
  ephysics_quaternion_axis_angle_set();
  ephysics_quaternion_get();
  ephysics_quaternion_set();

## ephysics_quaternion_set()

EAPI void ephysics_quaternion_set | ( | EPhysics_Quaternion * | quat,
|  | double | x,
|  | double | y,
|  | double | z,
|  | double | w )

Set quaternion values.

Parameters

  quat | Quaternion to be set.
  x | The x coordinate.
  y | The y coordinate.
  z | The z coordinate.
  w | The rotation.

See also
  ephysics_quaternion_get();
  ephysics_quaternion_euler_set();

Examples
  test_rotating_forever.c.

## ephysics_quaternion_axis_angle_set()

EAPI void ephysics_quaternion_axis_angle_set | ( | EPhysics_Quaternion * | quat,
|  | double | nx,
|  | double | ny,
|  | double | nz,
|  | double | a )

Set quaternion using axis angle notation.

[w, x, y, z] = [cos(a/2), sin(a/2) * nx, sin(a/2)* ny, sin(a/2) * nz]

Parameters

  quat | Quaternion to be set.
  nx | The x component of the axis of rotation.
  ny | The y component of the axis of rotation.
  nz | The z component of the axis of rotation.
  a | The angle of rotation.

See also
  ephysics_quaternion_axis_angle_get();
  ephysics_quaternion_set();
  ephysics_quaternion_euler_set();

## ephysics_quaternion_euler_set()

EAPI void ephysics_quaternion_euler_set | ( | EPhysics_Quaternion * | quat,
|  | double | yaw,
|  | double | pitch,
|  | double | roll )

Set quaternion using Euler angles.

It's an alternative to ephysics_quaternion_set() usage. Euler angles will be converted.

Parameters

  quat | Quaternion to be set.
  yaw | The angle around Y axis.
  pitch | The angle around X axis.
  roll | The angle around Z axis.

See also
  ephysics_quaternion_get();
  ephysics_quaternion_set();

## ephysics_quaternion_normalize()

EAPI void ephysics_quaternion_normalize | ( | EPhysics_Quaternion * | quat | ) |

Normalize the quaternion.

A normalized quaternion is such that x^2 + y^2 + z^2 + w^2 = 1.

Parameters

  quat | Quaternion to be normalized.

Examples
  test_rotating_forever.c.

## ephysics_quaternion_invert()

EAPI void ephysics_quaternion_invert | ( | EPhysics_Quaternion * | quat | ) |

Invert the quaternion.

Parameters

  quat | Quaternion to be inverted.

## ephysics_quaternion_scale()

EAPI void ephysics_quaternion_scale | ( | EPhysics_Quaternion * | quat,
|  | double | scale )

Scale the quaternion.

Parameters

  quat | Quaternion to be scaled.
  scale | The scale factor.

See also
  ephysics_quaternion_inverse_scale()

## ephysics_quaternion_inverse_scale()

EAPI void ephysics_quaternion_inverse_scale | ( | EPhysics_Quaternion * | quat,
|  | double | scale )

Inversely scale the quaternion.

Parameters

  quat | Quaternion to be scaled.
  scale | The scale factor.

See also
  ephysics_quaternion_scale()

## ephysics_quaternion_sum()

EAPI EPhysics_Quaternion * ephysics_quaternion_sum | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2,
|  | EPhysics_Quaternion * | result )

Returns a sum of two quaternions.

Parameters

  quat1 | First quaternion to sum.
  quat2 | Second quaternion to sum.
  result | Quaternion used to store the result. If it's `NULL`, a new quaternion will be allocated (and should be freed after usage).

Returns
  The sum quaternion or `NULL` on error.

## ephysics_quaternion_diff()

EAPI EPhysics_Quaternion * ephysics_quaternion_diff | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2,
|  | EPhysics_Quaternion * | result )

Returns a difference between two quaternions.

Parameters

  quat1 | First quaternion.
  quat2 | Second quaternion.
  result | Quaternion used to store the result. If it's `NULL`, a new quaternion will be allocated (and should be freed after usage).

Returns
  The difference between `quat1` and `quat2`, or `NULL` on error.

## ephysics_quaternion_multiply()

EAPI EPhysics_Quaternion * ephysics_quaternion_multiply | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2,
|  | EPhysics_Quaternion * | result )

Multiply two quaternions.

Parameters

  quat1 | First quaternion.
  quat2 | Second quaternion.
  result | Quaternion used to store the result. If it's `NULL`, a new quaternion will be allocated (and should be freed after usage).

Returns
  The `quat1` multiplied by `quat2` on the right, or `NULL` on error.

Examples
  test_rotating_forever.c.

## ephysics_quaternion_slerp()

EAPI EPhysics_Quaternion * ephysics_quaternion_slerp | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2,
|  | double | ratio,
|  | EPhysics_Quaternion * | result )

Return the quaternion which is the result of Spherical Linear Interpolation between two quaternions.

Slerp interpolates assuming constant velocity.

Parameters

  quat1 | First quaternion.
  quat2 | Second quaternion.
  ratio | The ratio between `quat1` and `quat2` to interpolate. If `ratio` = 0, the result is `quat1`, if `ratio` = 1, the result is `quat2`.
  result | Quaternion used to store the result. If it's `NULL`, a new quaternion will be allocated (and should be freed after usage).

Returns
  The result of slerp between `quat1` and `quat2`, or `NULL` on error.

## ephysics_quaternion_dot()

EAPI double ephysics_quaternion_dot | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2 )

Return the dot product between two quaternions.

Parameters

  quat1 | First quaternion.
  quat2 | Second quaternion.

Returns
  The dot product between `quat1` and `quat2` or `0` on error.

## ephysics_quaternion_angle_get()

EAPI double ephysics_quaternion_angle_get | ( | const EPhysics_Quaternion * | quat1,
|  | const EPhysics_Quaternion * | quat2 )

Return the angle between two quaternions.

Parameters

  quat1 | First quaternion.
  quat2 | Second quaternion.

Returns
  The angle between `quat1` and `quat2` or `0` on error.

## ephysics_quaternion_length_get()

EAPI double ephysics_quaternion_length_get | ( | const EPhysics_Quaternion * | quat | ) |

Return the length of the quaternion.

Parameters

  quat | Quaternion to get length of.

Returns
  The length of `quat` or `0` on error.

## ephysics_quaternion_length2_get()

EAPI double ephysics_quaternion_length2_get | ( | const EPhysics_Quaternion * | quat | ) |

Return the length squared of the quaternion.

Parameters

  quat | Quaternion to get length of.

Returns
  The length of `quat` or `0` on error.