EPhysics Quaternion

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

EPHYSICS_API 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();

References EPHYSICS_API, and ephysics_quaternion_new().

Referenced by ephysics_quaternion_new().

ephysics_quaternion_get()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_get().

Referenced by ephysics_quaternion_get().

ephysics_quaternion_axis_angle_get()

EPHYSICS_API 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();

References EPHYSICS_API, and ephysics_quaternion_axis_angle_get().

Referenced by ephysics_quaternion_axis_angle_get().

ephysics_quaternion_set()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_set().

Referenced by ephysics_quaternion_set().

ephysics_quaternion_axis_angle_set()

EPHYSICS_API 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();

References EPHYSICS_API, and ephysics_quaternion_axis_angle_set().

Referenced by ephysics_quaternion_axis_angle_set().

ephysics_quaternion_euler_set()

EPHYSICS_API 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();

References EPHYSICS_API, and ephysics_quaternion_euler_set().

Referenced by ephysics_quaternion_euler_set().

ephysics_quaternion_normalize()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_normalize().

Referenced by ephysics_quaternion_normalize().

ephysics_quaternion_invert()

EPHYSICS_API void ephysics_quaternion_invert

(

EPhysics_Quaternion *

quat

)

Invert the quaternion.

Parameters

quat	Quaternion to be inverted.

References EPHYSICS_API, and ephysics_quaternion_invert().

Referenced by ephysics_quaternion_invert().

ephysics_quaternion_scale()

EPHYSICS_API 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()

References EPHYSICS_API, and ephysics_quaternion_scale().

Referenced by ephysics_quaternion_scale().

ephysics_quaternion_inverse_scale()

EPHYSICS_API 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()

References EPHYSICS_API, and ephysics_quaternion_inverse_scale().

Referenced by ephysics_quaternion_inverse_scale().

ephysics_quaternion_sum()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_sum().

Referenced by ephysics_quaternion_sum().

ephysics_quaternion_diff()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_diff().

Referenced by ephysics_quaternion_diff().

ephysics_quaternion_multiply()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_multiply().

Referenced by ephysics_quaternion_multiply().

ephysics_quaternion_slerp()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_slerp().

Referenced by ephysics_quaternion_slerp().

ephysics_quaternion_dot()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_dot().

Referenced by ephysics_quaternion_dot().

ephysics_quaternion_angle_get()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_angle_get().

Referenced by ephysics_quaternion_angle_get().

ephysics_quaternion_length_get()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_length_get().

Referenced by ephysics_quaternion_length_get().

ephysics_quaternion_length2_get()

EPHYSICS_API 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.

References EPHYSICS_API, and ephysics_quaternion_length2_get().

Referenced by ephysics_quaternion_length2_get().