Skyline Lua API  Version 1.0
Lua Script Reference for Skyline Game Engine.
quat Class Reference

#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: