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

LUA_API_Vector3.h

Public Member Functions

Detailed Description

Member Function Documentation