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

`#include <LUA_API_Vector3.h>`

## Public Member Functions

float dotProduct (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Calculates the dot (scalar) product of this vector with another. More...

float absDotProduct (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Calculates the absolute dot (scalar) product of this vector with another. More...

float angle (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Gets the angle between 2 vectors. More...

float3 crossProduct (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Calculates the cross-product of 2 vectors, i.e. vector that lies perpendicular to them both. More...

int directionEquals (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance)
Returns whether this vector is within a directional tolerance of another vector. More...

float distance (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Returns the distance to another vector. More...

float4 getRotationTo (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float fallbackVec_X, float fallbackVec_Y, float fallbackVec_Z)
Gets the shortest arc quaternion to rotate this vector to the destination vector. More...

float3 midPoint (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Returns a vector at a point half way between this and the passed in vector. More...

float normalise (float vec1_X, float vec1_Y, float vec1_Z)
Normalises the vector. More...

float3 normalisedCopy (float vec1_X, float vec1_Y, float vec1_Z)
As normalise, except that this vector is unaffected and the normalised vector is returned as a copy. More...

float length (float vec1_X, float vec1_Y, float vec1_Z)
Returns the length (magnitude) of the vector. More...

int isNAN (float vec1_X, float vec1_Y, float vec1_Z)
Check whether this vector contains valid values. More...

int isZeroLength (float vec1_X, float vec1_Y, float vec1_Z)
Returns true if this vector is zero length. More...

float3 perpendicular (float vec1_X, float vec1_Y, float vec1_Z)
Generates a vector perpendicular to this vector (eg an 'up' vector). More...

int positionCloses (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance)
Returns whether this vector is within a positional tolerance of another vector, also take scale of the vectors into account. More...

int positionEquals (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance)
Returns whether this vector is within a positional tolerance of another vector. More...

float3 primaryAxis (float vec1_X, float vec1_Y, float vec1_Z)
Extract the primary (dominant) axis from this direction vector. More...

float3 randomDeviant (float vec1_X, float vec1_Y, float vec1_Z, float randomAngle, float vec2_X, float vec2_Y, float vec2_Z)
Generates a new random vector which deviates from this vector by a given angle in a random direction. More...

float3 reflect (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Calculates a reflection vector to the plane with the given normal . More...

float squaredDistance (float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z)
Returns the square of the distance to another vector. More...

float squaredLength (float vec1_X, float vec1_Y, float vec1_Z)
Returns the square of the length(magnitude) of the vector. More...

## Detailed Description

This area covers vector3 functions. Use as vector3.function(); This is a utility class that gives you access to many easy functions for vector mathmatics. For more information on how these functions can be used please visit the User Manual - https://home.aurasoft-skyline.co.uk

Example Cross Product of 2 vectors:

```Lua = crossProduct = newType.vec3(  vector3.crossProduct(vec1X, vec1Y, vec1Z, vec2X, vec2Y, vec2Z ) );
```

this is essentially doing :

```c++ = Vector3 return = vec1.crossProduct(vec2);
```

all functions that take in vec1 are the primary vector to do an operation on.

## Member Function Documentation

 float vector3::absDotProduct ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Calculates the absolute dot (scalar) product of this vector with another.

This function work similar dotProduct, except it use absolute value of each component of the vector to computing.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be used for the operation. vec2_Y : This is the Y Axis of the vector which will be used for the operation. vec2_Z : This is the Z Axis of the vector which will be used for the operation.
Returns
dotProduct : A float representing the absolute dot product value.
 float vector3::angle ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Gets the angle between 2 vectors.

Vectors do not have to be unit-length but must represent directions.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be used for the operation. vec2_Y : This is the Y Axis of the vector which will be used for the operation. vec2_Z : This is the Z Axis of the vector which will be used for the operation.
Returns
angle : This is a value in degrees of the angle between 2 vectors.
 float3 vector3::crossProduct ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Calculates the cross-product of 2 vectors, i.e. vector that lies perpendicular to them both.

The cross-product is normally used to calculate the normal vector of a plane, by calculating the cross-product of 2 non-equivalent vectors which lie on the plane (e.g. 2 edges of a triangle). For a clearer explanation, look a the left and the bottom edges of your monitor's screen. Assume that the first vector is the left edge and the second vector is the bottom edge, both of them starting from the lower-left corner of the screen. The resulting vector is going to be perpendicular to both of them and will go inside the screen, towards the cathode tube (assuming you're using a CRT monitor, of course).

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be used for the operation. vec2_Y : This is the Y Axis of the vector which will be used for the operation. vec2_Z : This is the Z Axis of the vector which will be used for the operation.
Returns
crossProduct : A float3 representing the vector3 which is the result of the cross-product. This vector will NOT be normalised, to maximise efficiency
 int vector3::directionEquals ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance )

Returns whether this vector is within a directional tolerance of another vector.

Note
Both vectors should be normalised.
Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be compared against. vec2_Y : This is the Y Axis of the vector which will be compared against. vec2_Z : This is the Z Axis of the vector which will be compared against. tolerance : The maximum angle in degrees by which the vectors may vary and still be considered equal
Returns
state : A boolean represented by 1 or 0 for true or false.
 float vector3::distance ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Returns the distance to another vector.

Warning
This operation requires a square root and is expensive in terms of CPU operations. If you don't need to know the exact distance (e.g. for just comparing distances) use squaredDistance() instead.
Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be compared against. vec2_Y : This is the Y Axis of the vector which will be compared against. vec2_Z : This is the Z Axis of the vector which will be compared against.
Returns
distance : The distance between vectors is returned as a float
 float vector3::dotProduct ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Calculates the dot (scalar) product of this vector with another.

The dot product can be used to calculate the angle between 2 vectors. If both are unit vectors, the dot product is the cosine of the angle; otherwise the dot product must be divided by the product of the lengths of both vectors to get the cosine of the angle. This result can further be used to calculate the distance of a point from a plane.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be used for the operation. vec2_Y : This is the Y Axis of the vector which will be used for the operation. vec2_Z : This is the Z Axis of the vector which will be used for the operation.
Returns
dotProduct : A float representing the dot product value.
 float4 vector3::getRotationTo ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float fallbackVec_X, float fallbackVec_Y, float fallbackVec_Z )

Gets the shortest arc quaternion to rotate this vector to the destination vector.

If you call this with a dest vector that is close to the inverse of this vector, we will rotate 180 degrees around the 'fallbackAxis' (if specified, or a generated axis if not) since in this case ANY axis of rotation is valid.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which is set as the destination. vec2_Y : This is the Y Axis of the vector which is set as the destination. vec2_Z : This is the Z Axis of the vector which is set as the destination. fallbackVec_X : This is the X Axis of the fallback vector. fallbackVec_Y : This is the Y Axis of the fallback vector. fallbackVec_Z : This is the Z Axis of the fallback vector.
Returns
rotation : Returned is the Quaternion rotation from the current vector, to the destination vector.
 int vector3::isNAN ( float vec1_X, float vec1_Y, float vec1_Z )

Check whether this vector contains valid values.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
state : A boolean represented by 1 or 0 for true or false.
 int vector3::isZeroLength ( float vec1_X, float vec1_Y, float vec1_Z )

Returns true if this vector is zero length.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
state : A boolean represented by 1 or 0 for true or false.
 float vector3::length ( float vec1_X, float vec1_Y, float vec1_Z )

Returns the length (magnitude) of the vector.

Warning
This operation requires a square root and is expensive in terms of CPU operations. If you don't need to know the exact length (e.g. for just comparing lengths) use squaredLength() instead.
Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
length : This will return the length of the vector. magnitude = (x1*x2) + (y1*y2) + (z1*z2);
 float3 vector3::midPoint ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Returns a vector at a point half way between this and the passed in vector.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be used for the operation. vec2_Y : This is the Y Axis of the vector which will be used for the operation. vec2_Z : This is the Z Axis of the vector which will be used for the operation.
Returns
midpoint : This will return a float3 representing a vector position that sits halfway between the 2 inputted vectors.
 float vector3::normalise ( float vec1_X, float vec1_Y, float vec1_Z )

Normalises the vector.

This method normalises the vector such that it's length / magnitude is 1. The result is called a unit vector. Most of the time, you will want to use normalisedCopy() to get the normalised float3 returned.

Note
This function will not crash for zero-sized vectors, but there will be no changes made to their components.
Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
previousLength : The previous length of the vector.
 float3 vector3::normalisedCopy ( float vec1_X, float vec1_Y, float vec1_Z )

As normalise, except that this vector is unaffected and the normalised vector is returned as a copy.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
normalised : This will return the normalised vector as float3.
 float3 vector3::perpendicular ( float vec1_X, float vec1_Y, float vec1_Z )

Generates a vector perpendicular to this vector (eg an 'up' vector).

This method will return a vector which is perpendicular to vector 1. There are an infinite number of possibilities but this method will guarantee to generate one of them.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
perpVector : A Perpendicular vector to the one pass through is returned as a float3.
 int vector3::positionCloses ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance )

Returns whether this vector is within a positional tolerance of another vector, also take scale of the vectors into account.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be compared against. vec2_Y : This is the Y Axis of the vector which will be compared against. vec2_Z : This is the Z Axis of the vector which will be compared against. tolerance : The amount (related to the scale of vectors) that distance of the vector may vary by and still be considered close
Returns
state : A boolean represented by 1 or 0 for true or false.
 int vector3::positionEquals ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z, float tolerance )

Returns whether this vector is within a positional tolerance of another vector.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be compared against. vec2_Y : This is the Y Axis of the vector which will be compared against. vec2_Z : This is the Z Axis of the vector which will be compared against. tolerance : The amount that each element of the vector may vary by and still be considered equal
Returns
state : A boolean represented by 1 or 0 for true or false.
 float3 vector3::primaryAxis ( float vec1_X, float vec1_Y, float vec1_Z )

Extract the primary (dominant) axis from this direction vector.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
primaryAxis : This is returned as a float 3 representing the vector3 primaryAxis.
 float3 vector3::randomDeviant ( float vec1_X, float vec1_Y, float vec1_Z, float randomAngle, float vec2_X, float vec2_Y, float vec2_Z )

Generates a new random vector which deviates from this vector by a given angle in a random direction.

This method assumes that the random number generator has already been seeded appropriately.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. angleDeg : The angle at which to deviate vec2_X : This is the X Axis of the vector which you are using as a direction. vec2_Y : This is the Y Axis of the vector which you are using as a direction. vec2_Z : This is the Z Axis of the vector which you are using as a direction.
Note
Any vector perpendicular to this one (which could generated by cross-product of this vector and any other non-colinear vector). If you choose not to provide this the function will derive one on it's own, however if you provide one yourself the function will be faster (this allows you to reuse up vectors if you call this method more than once)
Returns
randVector : A random vector as a float3 which deviates from this vector by angle. This vector will not be normalised, normalise it if you wish afterwards.
 float3 vector3::reflect ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Calculates a reflection vector to the plane with the given normal .

NB assumes 'this' is pointing AWAY FROM the plane, invert if it is not.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the normal to reflect on. vec2_Y : This is the Y Axis of the normal to reflect on. vec2_Z : This is the Z Axis of the normal to reflect on.
Returns
reflectVector : A vector which is reflected by the normal.
 float vector3::squaredDistance ( float vec1_X, float vec1_Y, float vec1_Z, float vec2_X, float vec2_Y, float vec2_Z )

Returns the square of the distance to another vector.

This method is for efficiency - calculating the actual distance to another vector requires a square root, which is expensive in terms of the operations required. This method returns the square of the distance to another vector, i.e. the same as the distance but before the square root is taken. Use this if you want to find the longest / shortest distance without incurring the square root.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on. vec2_X : This is the X Axis of the vector which will be compared against. vec2_Y : This is the Y Axis of the vector which will be compared against. vec2_Z : This is the Z Axis of the vector which will be compared against.
Returns
distance : A single float representing the distance between 2 vectors.
 float vector3::squaredLength ( float vec1_X, float vec1_Y, float vec1_Z )

Returns the square of the length(magnitude) of the vector.

This method is for efficiency - calculating the actual length of a vector requires a square root, which is expensive in terms of the operations required. This method returns the square of the length of the vector, i.e. the same as the length but before the square root is taken. Use this if you want to find the longest / shortest vector without incurring the square root.

Parameters
 vec1_X : This is the X Axis of the vector which you are going to use an operation on. vec1_Y : This is the Y Axis of the vector which you are going to use an operation on. vec1_Z : This is the Z Axis of the vector which you are going to use an operation on.
Returns
length : A single float representing the squared length of the vector.

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