Murl Engine Lua Addon API  Version 1.0 beta
Murl.Math.Vector

A 4-component vector class.


Table members

Enumerations


Component

Enumeration of the components raw data index. The components can be accessed by using the [] operator.

Murl.Math.Vector.XThe index to the X component.
Murl.Math.Vector.YThe index to the Y component.
Murl.Math.Vector.ZThe index to the Z component.
Murl.Math.Vector.WThe index to the W component.
Murl.Math.Vector.NUM_COMPONENTSThe number of components.

ComponentMask

Enumeration of the components' bit masks

Murl.Math.Vector.MASK_NONENo component
Murl.Math.Vector.MASK_XX component mask
Murl.Math.Vector.MASK_YY component mask
Murl.Math.Vector.MASK_ZZ component mask
Murl.Math.Vector.MASK_WW component mask
Murl.Math.Vector.MASK_XYComponent mask for X and Y
Murl.Math.Vector.MASK_XZComponent mask for X and Z
Murl.Math.Vector.MASK_YZComponent mask for Y and Z
Murl.Math.Vector.MASK_XYZComponent mask for X, Y and Z
Murl.Math.Vector.MASK_ALLAll components

PredefinedType

Enumeration of the predefined initialization types for constructing a Vector(PredefinedType type).

Murl.Math.Vector.ZERO_DIRECTIONInitialize with zero direction {0, 0, 0, 0}.
Murl.Math.Vector.ZERO_POSITIONInitialize with zero position {0, 0, 0, 1}.
Murl.Math.Vector.UNINITIALIZEDCreate an uninitialized instance.


Functions


Murl.Math.Vector.new()

The default constructor.

Murl.Math.Vector new()

Returns
Murl.Math.Vector

Murl.Math.Vector.new(type)

Constructor to create a vector from a predefined type.

Murl.Math.Vector new(Murl.Math.Vector.PredefinedType type)

Parameters
typeThe predefined type.
Returns
Murl.Math.Vector

Murl.Math.Vector.new(vx, vy, vz, vw)

Constructor to initialize a vector with given component values.

Murl.Math.Vector new(Number vx, Number vy, Number vz, Number vw)

Parameters
vxThe x component.
vyThe y component.
vzThe z component.
vwThe w component.
Returns
Murl.Math.Vector

Murl.Math.Vector.new(q)

Constructor to initialize an axis/angle vector from a quaternion.

Murl.Math.Vector new(Murl.Math.Quaternion q)

Parameters
qThe quaternion.
Returns
Murl.Math.Vector


Methods


Clear()

Clear all components of the vector instance. Set all components to default constructor of data type.

Clear()


Set(v)

Set all components of the vector instance to a given value.

Set(Number v)

Parameters
vThe value to set.

Set(vx, vy, vz, vw)

Set all components of the vector instance to a set of given component values.

Set(Number vx, Number vy, Number vz, Number vw)

Parameters
vxThe x-component value to set.
vyThe y-component value to set.
vzThe z-component value to set.
vwThe w-component value to set.

Set(q)

Convert a given quaternion to an axis/angle vector.

Set(Murl.Math.Quaternion q)

Parameters
qThe quaternion to convert from.

Set(v)

Copy the content of a source vector to the vector instance.

Set(Murl.Math.Vector v)

Parameters
vThe vector to copy from.

AddSelf(v)

In-place addition.

AddSelf(Murl.Math.Vector v)

Parameters
vThe vector to add.

SubtractSelf(v)

In-place subtraction.

SubtractSelf(Murl.Math.Vector v)

Parameters
vThe vector to subtract.

MultiplySelf(v)

In-place multiplication (scaling).

MultiplySelf(Number v)

Parameters
vThe value to multiply.

MultiplySelf(v)

In-place component-wise multiplication.

MultiplySelf(Murl.Math.Vector v)

Parameters
vThe vector to multiply.

DivideSelf(v)

In-place division (inverse scaling).

DivideSelf(Number v)

Parameters
vThe value to divide.

DivideSelf(v)

In-place component-wise division.

DivideSelf(Murl.Math.Vector v)

Parameters
vThe vector to divide.

CrossSelf(v)

In-place cross product.

CrossSelf(Murl.Math.Vector v)

Parameters
vThe vector to cross.

InterpolateSelf(v, t)

In-place linear interpolation. Interpolation along a straight line between the vector instance (first vector) and a given second vector. For t=0.0, the result equals the first vector and for t=1.0 the second one.

InterpolateSelf(Murl.Math.Vector v, Number t)

Parameters
vThe vector to interpolate.
tThe distance for interplation.

ProjectSelf(v)

In-place projection of a given second vector. Project the given second vector onto the vector instance (first vector). The first vector gets normalized and then multiplied by the length retrieved from a dot-product multiplication between the two vectors (i.e. the vector instance retains its direction, but retrieves the length of the projection).

ProjectSelf(Murl.Math.Vector v)

Parameters
vThe vector to project from.

MinSelf(v)

In-place set each component to the minimum from the vector instance and a given second vector.

MinSelf(Murl.Math.Vector v)

Parameters
vThe vector to evaluate the minimum from.

MaxSelf(v)

In-place set each component to the maximum from the vector instance and a given second vector.

MaxSelf(Murl.Math.Vector v)

Parameters
vThe vector to evaluate the maximum from.

ClampSelf(min, max)

In-place clamp each component to the value range given by the min and max vector parameters.

ClampSelf(Murl.Math.Vector min, Murl.Math.Vector max)

Parameters
minThe component-wise minimum to clamp to.
maxThe component-wise maximum to clamp to.

MinLengthSelf(v)

Rescale the vector to a length below or equal a given minimum. See MinLength().

MinLengthSelf(Number v)

Parameters
vThe minimum length.

MaxLengthSelf(v)

Rescale the vector to a length above or equal a given maximum. See MaxLength().

MaxLengthSelf(Number v)

Parameters
vThe maximum length.

ClampLengthSelf(min, max)

Clamp the vector to a length within a given range. See ClampLength().

ClampLengthSelf(Number min, Number max)

Parameters
minThe minimum length.
maxThe maximum length.

AbsSelf()

Set all vector components to their absolute value.

AbsSelf()


SgnSelf()

Set all vector components to either -1, 0 or +1 depending on their sign.

SgnSelf()


InvertSelf()

In-place inversion (negation) of the vector instance.

InvertSelf()


NormalizeSelf()

In-place normalization of the vector instance. Normalization retains the direction and sets the length to 1.0.

NormalizeSelf()


NormalizeAxisSelf()

In-place normalization of the x, y and z components. Calculates the normalization without touching the w component, for normalizing the axis of an axis/angle representation.

NormalizeAxisSelf()


Add(v)

Get the addition of a vector.

Murl.Math.Vector Add(Murl.Math.Vector v)

Parameters
vThe vector to add.
Returns
Murl.Math.Vector The added vector.

Subtract(v)

Get the subtraction of a vector.

Murl.Math.Vector Subtract(Murl.Math.Vector v)

Parameters
vThe vector to subtract.
Returns
Murl.Math.Vector The subtracted vector.

Multiply(v)

Get the multiplication (scaling).

Murl.Math.Vector Multiply(Number v)

Parameters
vThe value to multiply.
Returns
Murl.Math.Vector The multiplied vector.

Multiply(q)

Get the multiplication with a quaternion.

Murl.Math.Quaternion Multiply(Murl.Math.Quaternion q)

Parameters
qThe quaternion to multiply.
Returns
Murl.Math.Quaternion The multiplied quaternion.

Multiply(v)

Get the component-wise multiplication.

Murl.Math.Vector Multiply(Murl.Math.Vector v)

Parameters
vThe vector to multiply.
Returns
Murl.Math.Vector The multiplied vector.

Divide(v)

Get the division (inverse scaling).

Murl.Math.Vector Divide(Number v)

Parameters
vThe value to divide.
Returns
Murl.Math.Vector The divided vector.

Divide(v)

Get the component-wise division

Murl.Math.Vector Divide(Murl.Math.Vector v)

Parameters
vThe vector to divide.
Returns
Murl.Math.Vector The divided vector.

Cross(v)

Get the cross product.

Murl.Math.Vector Cross(Murl.Math.Vector v)

Parameters
vThe vector to cross.
Returns
Murl.Math.Vector The cross product vector.

Interpolate(v, t)

Get the linear interpolation. Interpolation along a straight line between the vector instance (first vector) and a given second vector. For t=0.0, the result equals the first vector and for t=1.0 the second one.

Murl.Math.Vector Interpolate(Murl.Math.Vector v, Number t)

Parameters
vThe vector to interpolate.
tThe interpolation factor.
Returns
Murl.Math.Vector The interpolated vector.

Project(v)

Get the projection of a given second vector. Project the given second vector onto the vector instance (first vector). The first vector gets normalized and then multiplied by the length retrieved from a dot-product multiplication between the two vectors (i.e. the vector instance retains its direction, but retrieves the length of the projection).

Murl.Math.Vector Project(Murl.Math.Vector v)

Parameters
vThe vector to project from.
Returns
Murl.Math.Vector The projected vector.

Min(v)

Get the minimum of each component from the vector instance and a given second vector.

Murl.Math.Vector Min(Murl.Math.Vector v)

Parameters
vThe vector to evaluate the minimum from.
Returns
Murl.Math.Vector The minimum vector.

Max(v)

Get the maximum of each component from the vector instance and a given second vector.

Murl.Math.Vector Max(Murl.Math.Vector v)

Parameters
vThe vector to evaluate the maximum from.
Returns
Murl.Math.Vector The maximum vector.

Clamp(min, max)

Clamp each component to the value range given by the min and max vector parameters.

Murl.Math.Vector Clamp(Murl.Math.Vector min, Murl.Math.Vector max)

Parameters
minThe component-wise minimum to clamp to.
maxThe component-wise maximum to clamp to.
Returns
Murl.Math.Vector The clamped vector.

MinLength(v)

Get a vector with a length below or equal a given minimum. If the current vector's length is below or equal the given minimum value, the vector is directly returned. Otherwise a scaled vector is returned, with the original direction and given length.

Murl.Math.Vector MinLength(Number v)

Parameters
vThe minimum length.
Returns
Murl.Math.Vector A minimum length vector.

MaxLength(v)

Get a vector with a length above or equal a given maximum. If the current vector's length is above or equal the given maximum value, the vector is directly returned. Otherwise a scaled vector is returned, with the original direction and given length. If the vector has zero length (i.e. undefined direction) a zero vector is returned with its w component set to either 0 or 1, depending on the current vector's w value.

Murl.Math.Vector MaxLength(Number v)

Parameters
vThe maximum length.
Returns
Murl.Math.Vector A maximum length vector.

ClampLength(min, max)

Get the a vector with clamped length. This method returns a vector in the direction of the vector instance, but with its length clamped to the given range.

Murl.Math.Vector ClampLength(Number min, Number max)

Parameters
minThe minimum length.
maxThe maximum length.
Returns
Murl.Math.Vector A clamped vector.

Abs()

Get a vector containing absolute values for each of the instance's components.

Murl.Math.Vector Abs()

Returns
Murl.Math.Vector The resulting vector.

Sgn()

Get a vector containing component values of either -1, 0 or +1, depending on the instance component's signs.

Murl.Math.Vector Sgn()

Returns
Murl.Math.Vector The resulting vector.

Invert()

Get the inversion (negation) of the vector instance.

Murl.Math.Vector Invert()

Returns
Murl.Math.Vector The inverted vector.

Normalize()

Get the normalization of the vector instance. Normalization retains the direction and sets the length to 1.0.

Murl.Math.Vector Normalize()

Returns
Murl.Math.Vector The normalized vector.

NormalizeAxis()

Get the normalization of the x, y and z components. Calculates the normalization without touching the w component, for normalizing the axis of an axis/angle representation.

Murl.Math.Vector NormalizeAxis()

Returns
Murl.Math.Vector The normalized axis vector.

Dot(v)

Get the dot product of the vector instance and a given second vector.

Number Dot(Murl.Math.Vector v)

Parameters
vThe second vector.
Returns
Number The dot product.

GetLength()

Get the length of the vector instance.

Number GetLength()

Returns
Number The length of the vector.

GetSquaredLength()

Get the squared length of the vector instance.

Number GetSquaredLength()

Returns
Number The squared length of the vector.

GetAngle2D()

Get the x/y angle of the vector instance.

Number GetAngle2D()

Returns
Number The angle in radians [0 .. 2π].

IsZero()

Check if the vector instance equals the null vector. Compares all values within the default epsilon range Limits::Epsilon().

Boolean IsZero()

Returns
Boolean true if equals the null vector.

IsZero(epsilon)

Check if the vector instance equals the null vector. Compares all values within a given epsilon range.

Boolean IsZero(Number epsilon)

Parameters
epsilonThe epsilon to compare.
Returns
Boolean true if equals the null vector.

IsZeroPosition()

Check if the vector instance equals the zero position. Compares the x, y and z values within the default epsilon range Limits::Epsilon().

Boolean IsZeroPosition()

Returns
Boolean true if equals the null vector.

IsZeroPosition(epsilon)

Check if the vector instance equals the zero position. Compares the x, y and z values within a given epsilon range.

Boolean IsZeroPosition(Number epsilon)

Parameters
epsilonThe epsilon to compare.
Returns
Boolean true if equals the null vector.

IsEqual(v)

Check if the vector instance is equal to a given second vector. Compares all values within the default epsilon range Limits::Epsilon().

Boolean IsEqual(Murl.Math.Vector v)

Parameters
vThe vector to compare.
Returns
Boolean true if equal to the compared vector.

IsEqual(v, epsilon)

Check if the vector instance is equal to a given second vector. Compares all values within a given epsilon range.

Boolean IsEqual(Murl.Math.Vector v, Number epsilon)

Parameters
vThe vector to compare.
epsilonThe epsilon to compare.
Returns
Boolean true if equal to the compared vector.

GetBaseNormals(n1, n2, n3)

Get base vectors for this vector instance. This method tries to calculate three direction vectors from the current instance, so that they form an orthonormal base. If the current vector has zero length, false is returned.

Boolean, Murl.Math.Vector, Murl.Math.Vector, Murl.Math.Vector GetBaseNormals(Murl.Math.Vector n1, Murl.Math.Vector n2, Murl.Math.Vector n3)

Parameters
n1Base vector 1
n2Base vector 2
n3Base vector 3
Returns
Boolean true if successful.
Murl.Math.Vector n1 Base vector 1
Murl.Math.Vector n2 Base vector 2
Murl.Math.Vector n3 Base vector 3

ToString()

Get the string representation of the object.

String ToString()

Returns
String The string representation of the object.

GetCount()

Get the number of elements in the object.

Integer GetCount()

Returns
Integer The number of elements in the object.


Metamethods


The length operator

The length operator is denoted by the unary prefix operator #.

Returns
GetCount()

The tostring operator

Converts the object content to a string in a reasonable format.

Returns
ToString()

The array subscript operator.

Get a reference to one of the 4 component values.

Parameters
indexThe component index, see enum Component.
Returns
Number = Murl.Math.Vector [Integer index]
Assign
Murl.Math.Vector [Integer index] = Number

The addition operator.

Addition operator.

Returns
Murl.Math.Vector = Murl.Math.Vector + Murl.Math.Vector

The unary minus operator.

Inversion (negation) operator.

Returns
Murl.Math.Vector = - Murl.Math.Vector

The subtraction operator.

Subtraction operator.

Returns
Murl.Math.Vector = Murl.Math.Vector - Murl.Math.Vector

The multiplication operator.

Multiplication (scaling) operator.

Returns
Murl.Math.Vector = Murl.Math.Vector * Number

The multiplication operator.

Multiplication operator for quaternion.

Returns
Murl.Math.Quaternion = Murl.Math.Vector * Murl.Math.Quaternion

The multiplication operator.

Component-wise multiplication operator.

Returns
Murl.Math.Vector = Murl.Math.Vector * Murl.Math.Vector

The division operator.

Division (inverse scaling) operator.

Returns
Murl.Math.Vector = Murl.Math.Vector / Number

The division operator.

Component-wise division operator.

Returns
Murl.Math.Vector = Murl.Math.Vector / Murl.Math.Vector

The equal to operator.

Equal to comparison operator. Performs a test without an epsilon range, which can be used for detecting changes i.e. DoubleBuffer<Vector> class. To compare within an epsilon range use Vector::IsEqual().

Returns
Boolean = Murl.Math.Vector == Murl.Math.Vector


Instance Members


x

The X component.

Returns
Number

y

The Y component.

Returns
Number

z

The Z component.

Returns
Number

w

The W component.

Returns
Number