#include <LUA_API_Quaternion.h>

Public Member Functions
void	newQuat (string quatName, float w, float x, float y, float z)
	Call this function and pass the arguments to create a new Quaternion. More...

void	newQuatFromAngleAxis (string quatName, float angleDegrees, float axisX, float axisY, float axisZ)
	Create a new Quaternion from an angle on a particular Axis. More...

float4	getQuat (string quatName)
	Return the Quaternion referenced by name into a float4. More...

float4	slerp (float rotProgress, float srcW, float srcX, float srcY, float srcZ, float destW, float destX, float destY, float destZ, int shortPath)
	Call this function to create smooth rotations between a source rotation and a destination rotation over time. Advanced : Performs Spherical linear interpolation between two quaternions, and returns the result. More...

float	getYaw (string quatName, int degreeOrRadians)
	Return the Yaw Value of the specified Quaternion. Either Return the Yaw in Degrees or Radians. More...

float	getPitch (string quatName, int degreeOrRadians)
	Return the Pitch Value of the specified Quaternion. Either Return the Pitch in Degrees or Radians. More...

float	getRoll (string quatName, int degreeOrRadians)
	Return the Roll Value of the specified Quaternion. Either Return the Roll in Degrees or Radians. More...

float3	getRollPitchYaw (string quatName, int degreeOrRadians)
	Returns Yaw, Pitch and Roll Values of the specified Quaternion. Either Return the Yaw in Degrees or Radians. More...

int	getW (string quatName)
	Get the W Component of the Quaternion Specified. More...

int	getX (string quatName)
	Get the X Component of the Quaternion Specified. More...

int	getY (string quatName)
	Get the Y Component of the Quaternion Specified. More...

int	getZ (string quatName)
	Get the Z Component of the Quaternion Specified. More...

void	setW (string quatName, float quatW)
	Set the W Component of the Quaternion Specified. More...

void	setX (string quatName, float quatX)
	Set the X Component of the Quaternion Specified. More...

void	setY (string quatName, float quatY)
	Set the Y Component of the Quaternion Specified. More...

void	setZ (string quatName, float quatZ)
	Set the Z Component of the Quaternion Specified. More...

float4	setQuatValues (string quatName, float w, float x, float y, float z)
	Set all 4 Quaternion Components to the Quaternion specified. More...

float4	multiply (string quatName, string quatName2)
	Multiply two Quaternions Together. More...

void	inverse (string quatName)
	Inverse the Quaternion. More...

void	normalise (string quatName)
	Normalise the Quaternion. More...

float4	getXAxis_RotationTo (string quatName, float posX, float posY, float posZ)
	get the rotation on the X Axis from a particular axis and position. More...

float4	getYAxis_RotationTo (string quatName, float posX, float posY, float posZ)
	get the rotation on the Y Axis from a particular axis and position. More...

float4	getZAxis_RotationTo (string quatName, float posX, float posY, float posZ)
	get the rotation on the Z Axis from a particular axis and position. More...

float4	rotateOrientation (float degree, int axisX, int axisY, int axisZ, float rotW, float rotX, float rotY, float rotZ)
	rotate a quaternion orientation passed in by a certain degree on the specific axis This will allow you to easily flip a rotation 180 degrees or by 90 degrees for example on the y More...

Detailed Description

The following Quaternion functions will help you when dealing with quaternions in lua.
Use as quat.function()
For more information on how these functions can be used please visit the User Manual - https://home.aurasoft-skyline.co.uk

The following script shows the quat class at work.
It makes one object rotate and face another.
Try adding an object move action to the non rotating object and see the quaternions at play.

obj         = entity.getEntityIDFromTag("cube_1");
targetID    = entity.getEntityIDFromTag("cube_2");
rotProgress = 0;
rotDelay    = 200;
rotFactor   = 1.0/rotDelay;

function rotateObject()
    dirX,dirY,dirZ = entity.subtractPositions(targetID,obj)
    srcX,srcY,srcZ = entity.getLocalOrientationByAxis(obj,0,0,1) 
    
    quatW,quatX,quatY,quatZ = entity.getRotationTo(srcX,srcY,srcZ,dirX,dirY,dirZ)
    quat.newQuat("lookatObject_getRotTo",quatW,quatX,quatY,quatZ)
    
    OriSrcW,OriSrcX,OriSrcY,OriSrcZ = entity.getLocalOrientation(obj);
    quat.newQuat("lookatObject_OriSrc",OriSrcW,OriSrcX,OriSrcY,OriSrcZ)

    OriDestW,OriDestX,OriDestY,OriDestZ = quat.multiply("lookatObject_getRotTo","lookatObject_OriSrc")
    quat.newQuat("lookatObject_OriDest",OriDestW,OriDestX,OriDestY,OriDestZ)
    rotProgress = rotProgress + rotFactor;
    
    if(rotProgress >= 1)then
        rotProgress = 0
    else
        deltaW,deltaX,deltaY,deltaZ = quat.slerp(rotProgress,OriSrcW,OriSrcX,OriSrcY,OriSrcZ,OriDestW,OriDestX,OriDestY,OriDestZ,1)
        entity.setLocalOrientation(obj,deltaW,deltaX,deltaY,deltaZ)
    end
end

function onUpdate()
    rotateObject();
end

Member Function Documentation

float quat::getPitch	(	string	quatName,
		int	degreeOrRadians
	)

Return the Pitch Value of the specified Quaternion. Either Return the Pitch in Degrees or Radians.

Parameters

quatName	: Name of the Quaternion for the values to return from.
degreeOrRadians	: Set to use Degrees or Radians. 0 = Degrees, 1 = Radians. Use enum.rotateDegree() or enum.rotateRadian().

Returns: pitch: Returns the Pitch Value of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    x = quat.getPitch("Quat_Name",enum.rotateDegree()); 
end

float4 quat::getQuat ( string quatName )

Return the Quaternion referenced by name into a float4.

Parameters

quatName : Name of the Quaternion for the values to return from.

Returns: QuatW : Returns the Quaternion W Component.; QuatX : Returns the Quaternion X Component.; QuatY : Returns the Quaternion Y Component.; QuatZ : Returns the Quaternion Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    w,x,y,z = quat.getQuat("Quat_Name"); 
end

float quat::getRoll	(	string	quatName,
		int	degreeOrRadians
	)

Return the Roll Value of the specified Quaternion. Either Return the Roll in Degrees or Radians.

Parameters

quatName	: Name of the Quaternion for the values to return from.
degreeOrRadians	: Set to use Degrees or Radians. 0 = Degrees, 1 = Radians. Use enum.rotateDegree() or enum.rotateRadian().

Returns: roll: Returns the Roll Value of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    z = quat.getRoll("Quat_Name",enum.rotateDegree()); 
end

float3 quat::getRollPitchYaw	(	string	quatName,
		int	degreeOrRadians
	)

Returns Yaw, Pitch and Roll Values of the specified Quaternion. Either Return the Yaw in Degrees or Radians.

Parameters

quatName	: Name of the Quaternion for the values to return from.
degreeOrRadians	: Set to use Degrees or Radians. 0 = Degrees, 1 = Radians. Use enum.rotateDegree() or enum.rotateRadian().

Returns: yaw: Returns the Yaw Value of the Quaternion.; pitch: Returns the Yaw Value of the Quaternion.; roll: Returns the Yaw Value of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    x,y,z = quat.getRollPitchYaw("Quat_Name",enum.rotateDegree()); 
end

int quat::getW ( string quatName )

Get the W Component of the Quaternion Specified.

Parameters

quatName : The Quaternion to return the Component from.

Returns: quatW : The W Component of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    w = quat.getW("Quat_Name");
end

int quat::getX ( string quatName )

Get the X Component of the Quaternion Specified.

Parameters

quatName : The Quaternion to return the Component from.

Returns: quatW : The X Component of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    x = quat.getX("Quat_Name");
end

float4 quat::getXAxis_RotationTo	(	string	quatName,
		float	posX,
		float	posY,
		float	posZ
	)

get the rotation on the X Axis from a particular axis and position.

Parameters

quatName	: The name of the Quaternion to access
posX	: pass the X Axis of the world space position
posY	: pass the Y Axis of the world space position
posZ	: pass the Z Axis of the world space position

Returns: w : Returns the W Component of the returned quaternion rotation; x : Returns the W Component of the returned quaternion rotation; y : Returns the W Component of the returned quaternion rotation; z : Returns the W Component of the returned quaternion rotation

The following is a Small Example on how to use this function:

function onInit(objID)
    w,x,y,z = quat.getXAxis_RotationTo("Quat_Name", 0, 0, 0);
end

int quat::getY ( string quatName )

Get the Y Component of the Quaternion Specified.

Parameters

quatName : The Quaternion to return the Component from.

Returns: quatW : The Y Component of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    y = quat.getY("Quat_Name");
end

float quat::getYaw	(	string	quatName,
		int	degreeOrRadians
	)

Return the Yaw Value of the specified Quaternion. Either Return the Yaw in Degrees or Radians.

Parameters

quatName	: Name of the Quaternion for the values to return from.
degreeOrRadians	: Set to use Degrees or Radians. 0 = Degrees, 1 = Radians. Use enum.rotateDegree() or enum.rotateRadian().

Returns: yaw: Returns the Yaw Value of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    y = quat.getYaw("Quat_Name",enum.rotateDegree()); 
end

float4 quat::getYAxis_RotationTo	(	string	quatName,
		float	posX,
		float	posY,
		float	posZ
	)

get the rotation on the Y Axis from a particular axis and position.

Parameters

quatName	: The name of the Quaternion to access
posX	: pass the X Axis of the world space position
posY	: pass the Y Axis of the world space position
posZ	: pass the Z Axis of the world space position

Returns: w : Returns the W Component of the returned quaternion rotation; x : Returns the W Component of the returned quaternion rotation; y : Returns the W Component of the returned quaternion rotation; z : Returns the W Component of the returned quaternion rotation

The following is a Small Example on how to use this function:

function onInit(objID)
    w,x,y,z = quat.getYAxis_RotationTo("Quat_Name", 0, 0, 0);
end

int quat::getZ ( string quatName )

Get the Z Component of the Quaternion Specified.

Parameters

quatName : The Quaternion to return the Component from.

Returns: quatW : The Z Component of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    z = quat.getZ("Quat_Name");
end

float4 quat::getZAxis_RotationTo	(	string	quatName,
		float	posX,
		float	posY,
		float	posZ
	)

get the rotation on the Z Axis from a particular axis and position.

Parameters

quatName	: The name of the Quaternion to access
posX	: pass the X Axis of the world space position
posY	: pass the Y Axis of the world space position
posZ	: pass the Z Axis of the world space position

Returns: w : Returns the W Component of the returned quaternion rotation; x : Returns the X Component of the returned quaternion rotation; y : Returns the Y Component of the returned quaternion rotation; z : Returns the Z Component of the returned quaternion rotation

The following is a Small Example on how to use this function:

function onInit(objID)
    w,x,y,z = quat.getZAxis_RotationTo("Quat_Name", 0, 0, 0);
end

void quat::inverse ( string quatName )

Inverse the Quaternion.

Parameters

quatName : The name of the Quaternion to Inverse values.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.inverse("Quat_Name");
end

float4 quat::multiply	(	string	quatName,
		string	quatName2
	)

Multiply two Quaternions Together.

Parameters

quatName	: The first Quaternion to multiply against.
quatName2	: The second Quaternion to multiply against.

Returns: w : Returns the W Component of the two multiplied Quaternions.; x : Returns the X Component of the two multiplied Quaternions.; y : Returns the Y Component of the two multiplied Quaternions.; z : Returns the Z Component of the two multiplied Quaternions.

The following is a Small Example on how to use this function:

function onInit(objID)
    w,x,y,z = quat.multiply("Quat_Name", "Quat_Name2" );
end

void quat::newQuat	(	string	quatName,
		float	w,
		float	x,
		float	y,
		float	z
	)

Call this function and pass the arguments to create a new Quaternion.

Parameters

quatName	: set the name of the quaternion. Important :: You will need to access this quaternion using the name every time. Choose name wisely. Also the name must only be used once.
w	: Set the W Component of the Quaternion.
x	: Set the X Component of the Quaternion.
y	: Set the Y Component of the Quaternion.
z	: Set the Z Component of the Quaternion.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.newQuat("Quat_Name",0,0,0,0);
end

void quat::newQuatFromAngleAxis	(	string	quatName,
		float	angleDegrees,
		float	axisX,
		float	axisY,
		float	axisZ
	)

Create a new Quaternion from an angle on a particular Axis.

Parameters

quatName	: set the name of the quaternion. Important :: You will need to access this quaternion using the name every time. Choose name wisely. Also the name must only be used once.
angleDegrees	: Set the Angle in Degrees to set the Particular Axis to.
axisX	: Set whether to work on the X Axis. Set this Value to 1 and the others to 0.
axisY	: Set whether to work on the Y Axis. Set this Value to 1 and the others to 0.
axisZ	: Set whether to work on the Z Axis. Set this Value to 1 and the others to 0.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.newQuatFromAngleAxis("Quat_Name",90,0,1,0);
end

void quat::normalise ( string quatName )

Normalise the Quaternion.

Parameters

quatName : The name of the Quaternion to Normalise.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.normalise("Quat_Name");
end

float4 quat::rotateOrientation	(	float	degree,
		int	axisX,
		int	axisY,
		int	axisZ,
		float	rotW,
		float	rotX,
		float	rotY,
		float	rotZ
	)

rotate a quaternion orientation passed in by a certain degree on the specific axis This will allow you to easily flip a rotation 180 degrees or by 90 degrees for example on the y

Parameters

degree	: The name of the Quaternion to access
axisX	: Set to 1 to rotate on the X Axis or 0 to not rotate on this axis
axisY	: Set to 1 to rotate on the Y Axis or 0 to not rotate on this axis
axisZ	: Set to 1 to rotate on the Z Axis or 0 to not rotate on this axis
rotW	: The Quaternion W value to pass in to rotate by a degree
rotX	: The Quaternion X value to pass in to rotate by a degree
rotY	: The Quaternion Y value to pass in to rotate by a degree
rotZ	: The Quaternion Z value to pass in to rotate by a degree

Returns: w : Returns the W Component of the returned quaternion rotation which has been rotated; x : Returns the X Component of the returned quaternion rotation which has been rotated; y : Returns the Y Component of the returned quaternion rotation which has been rotated; z : Returns the Z Component of the returned quaternion rotation which has been rotated

The following is a Small Example on how to use this function:

function onInit(objID)
    obj = objID;
    axis = newType.vec3(0,1,0);
    rot = newType.vec4(entity.getWorldOrientation(obj));
    degree = 180; 
    rotateQuat = newType.vec4(quat.rotateOrientation(degree, axis.x, axis.y, axis.z, rot.w, rot.x, rot.y, rot.z));
end

float4 quat::setQuatValues	(	string	quatName,
		float	w,
		float	x,
		float	y,
		float	z
	)

Set all 4 Quaternion Components to the Quaternion specified.

Parameters

quatName	: The Quaternion to set the Component to.
w	: The W Component value of the Quaternion to set.
x	: The X Component value of the Quaternion to set.
y	: The Y Component value of the Quaternion to set.
z	: The Z Component value of the Quaternion to set.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.setQuatValues("Quat_Name", 0, 0, 0, 0 );
end

void quat::setW	(	string	quatName,
		float	quatW
	)

Set the W Component of the Quaternion Specified.

Parameters

quatName	: The Quaternion to set the Component to.
quatW	: The W Component value of the Quaternion to set.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.setW("Quat_Name", 0);
end

void quat::setX	(	string	quatName,
		float	quatX
	)

Set the X Component of the Quaternion Specified.

Parameters

quatName	: The Quaternion to set the Component to.
quatW	: The X Component value of the Quaternion to set.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.setX("Quat_Name", 0);
end

void quat::setY	(	string	quatName,
		float	quatY
	)

Set the Y Component of the Quaternion Specified.

Parameters

quatName	: The Quaternion to set the Component to.
quatW	: The Y Component value of the Quaternion to set.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.setY("Quat_Name", 0);
end

void quat::setZ	(	string	quatName,
		float	quatZ
	)

Set the Z Component of the Quaternion Specified.

Parameters

quatName	: The Quaternion to set the Component to.
quatZ	: The Z Component value of the Quaternion to set.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat.setZ("Quat_Name", 0);
end

float4 quat::slerp	(	float	rotProgress,
		float	srcW,
		float	srcX,
		float	srcY,
		float	srcZ,
		float	destW,
		float	destX,
		float	destY,
		float	destZ,
		int	shortPath
	)

Call this function to create smooth rotations between a source rotation and a destination rotation over time.
Advanced : Performs Spherical linear interpolation between two quaternions, and returns the result.

Parameters

rotProgress	: Rotation Value over time. 0 = Source Rotation; 1 = Destination Rotation.
srcW	: Source Quaternion W Rotation Value.
srcX	: Source Quaternion X Rotation Value.
srcY	: Source Quaternion Y Rotation Value.
srcZ	: Source Quaternion Z Rotation Value.
destW	: Destination Quaternion W Rotation Value.
destX	: Destination Quaternion X Rotation Value.
destY	: Destination Quaternion Y Rotation Value.
destZ	: Destination Quaternion Z Rotation Value.
shortPath	: see below text->

Slerp has the proprieties of performing the interpolation at constant velocity,
and being torque-minimal (unless shortestPath=false). However, it's NOT commutative,
which means Slerp ( 0.75f, A, B ) != Slerp ( 0.25f, B, A ); therefore be careful if
your code relies in the order of the operands. This is specially important in IK animation.

The following is a Small Example on how to use this function:

function onUpdate(objID)
    W,X,Y,Z = quat.slerp(rotProgress,srcW,srcX,srcY,srcZ,destW,destX,destY,destZ,1);
    entity.setLocalOrientation(entity.getEntityIDFromTag("cube_1"),W,X,Y,Z)
end

The documentation for this class was generated from the following file:

LUA_API_Quaternion.h

Public Member Functions

Detailed Description

Member Function Documentation