Vectors

Vector types

The following vector types are provided by LuaCML:

Type Description
vector2 A two-element vector based on lua_Number
vector3 A three-element vector based on lua_Number
vector4 A four-element vector based on lua_Number

Vector functions

constructor

Vectors have default constructors initialized with zeros:

local foo = luacml.vector3() -- set to (0,0,0)

Vectors can be constructed from individual numbers:

local foo = luacml.vector4(1,2,3,4)

Or from a table of numbers:

local foo = luacml.vector2({1,2})

Or from another vector:

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(foo) -- set to (1,2,3)

Parameters

Returns

The newly constructed vector.

Errors

set()

Vectors can be set from individual numbers:

local foo = luacml.vector3()
foo:set(1,2,3)

Or from a table of numbers:

local foo = luacml.vector3()
foo:set({1,2,3})

Or from another vector:

local foo = luacml.vector3()
foo:set(luacml.vector3(1,2,3))

Parameters

Returns

The vector, after it has been set.

Errors

totable()

Vectors can be converted to a table:

local foo = luacml.vector3(1,2,3)
local bar = foo:totable()
print(bar[1], bar[2], bar[3]) -- prints: 1 2 3

Parameters

(None)

Returns

An array containing the vector's elements.

Errors

length()

The length of a vector can be found:

local foo = luacml.vector3(1,2,3)
print(foo:length())

Parameters

(None)

Returns

The vector's length as a number.

Errors

length_squared()

The squared-length of a vector can be found:

local foo = luacml.vector3(1,2,3)
print(foo:length_squared())

Parameters

(None)

Returns

The vector's squared length as a number.

Errors

normalize()

A vector can be normalized in-place:

local foo = luacml.vector3(1,2,3)
foo:normalize()

Parameters

(None)

Returns

The vector, after it has been normalized.

Errors

zero()

A vector can be zeroed in-place:

local foo = luacml.vector3(1,2,3)
foo:zero()

Parameters

(None)

Returns

The vector, after it has been zeroed.

Errors

cardinal()

A vector can be set to a cardinal axis:

local foo = luacml.vector3(1,2,3)
foo:cardinal(1) -- sets to <1,0,0>
foo:cardinal(2) -- sets to <0,1,0>
foo:cardinal(3) -- sets to <0,0,1>

Parameters

An integer from 1 to N for a vector of size N.

Returns

The vector, after it has been set.

Errors

minimize()

A vector can be set to the element-wise minimum of itself and another vector.

local foo = luacml.vector3(10,20,30)
local bar = luacml.vector3(1,200,29)
foo:minimize(bar) -- sets to <1,20,29>

Parameters

A vector of same size.

Returns

(None)

Errors

maximize()

A vector can be set to the element-wise maximum of itself and another vector.

local foo = luacml.vector3(10,20,30)
local bar = luacml.vector3(1,200,29)
foo:maximize(bar) -- sets to <10,200,30>

Parameters

A vector of same size.

Returns

(None)

Errors

random()

A vector can be set to a random vector with elements between specified minimum and maximum values.

local foo = luacml.vector3()
foo:random(-1,1) -- sets each element to a random value between -1 and 1.

Parameters

Returns

(None)

Errors

add()

A vector can be added with another vector.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(1,2,3)
print(foo:add(bar)) -- prints: vector3:<2,4,6>
print(foo)          -- prints: vector3:<1,2,3>

Note

The original vectors are unchanged.

Internally, this equivalent to the __add metamethod.

Parameters

A vector of same type.

Returns

A new vector representing the element-wise sum.

Errors

sub()

A vector can be added with another vector.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(1,2,3)
print(foo:sub(bar)) -- prints: vector3:<0,0,0>
print(foo)          -- prints: vector3:<1,2,3>

Note

The original vectors are unchanged.

Internally, this function is equivalent to the __sub metamethod.

Parameters

A vector of same type.

Returns

A new vector representing the element-wise difference.

Errors

mul()

A vector can be scaled with a number.

local foo = luacml.vector3(1,2,3)
print(foo:mul(2)) -- prints: vector3:<2,4,6>
print(foo)        -- prints: vector3:<1,2,3>

Note

The original vector is unchanged.

Internally, this function is equivalent to the __mul metamethod.

Parameters

A scalar number.

Returns

A new vector representing the element-wise scale.

Errors

div()

A vector can be inverse-scaled with a number.

local foo = luacml.vector3(2,4,6)
print(foo:div(2)) -- prints: vector3:<1,2,3>
print(foo)        -- prints: vector3:<2,4,6>

Note

The original vector is unchanged.

Internally, this function is equivalent to the __div metamethod.

Parameters

A scalar number.

Returns

A new vector representing the element-wise division.

Errors

addeq()

A vector can be incremented in-place with another vector.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(1,2,3)
print(foo:addeq(bar)) -- prints: vector3:<2,4,6>
print(foo)            -- prints: vector3:<2,4,6>

Note

The original vector (not the parameter) is updated.

Parameters

A vector of same type.

Returns

The updated vector after the element-wise sum.

Errors

subeq()

A vector can be subtracted in-place with another vector.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(1,2,3)
print(foo:subeq(bar)) -- prints: vector3:<0,0,0>
print(foo)            -- prints: vector3:<0,0,0>

Note

The original vector (not the parameter) is updated.

Parameters

A vector of same type.

Returns

The updated vector after the element-wise subtraction.

Errors

muleq()

A vector can be scaled in-place with a number.

local foo = luacml.vector3(1,2,3)
print(foo:muleq(2)) -- prints: vector3:<2,4,6>
print(foo)          -- prints: vector3:<2,4,6>

Note

The original vector (not the parameter) is updated.

Parameters

A scalar number.

Returns

The updated vector after the element-wise multiplication.

Errors

diveq()

A vector can be inverse-scaled with a number.

local foo = luacml.vector3(2,4,6)
print(foo:diveq(2)) -- prints: vector3:<1,2,3>
print(foo)          -- prints: vector3:<1,2,3>

Note

The original vector (not the parameter) is updated.

Parameters

A scalar number.

Returns

The updated vector after the element-wise division.

Errors

Vector metamethods

All vector types have a set of metamethods that allow them to be used with several operators.

__index

The __index metamethod permits vector element access.

Vectors can be indexed with 1-based integer keys:

local foo = luacml.vector2(10,20)
print(foo[1]) -- prints: 10

Or with case-insensitive "x", "y", "z", or "w" string keys:

local foo = luacml.vector3(10,20,30)
print(foo.x)    -- prints: 10
print(foo.Y)    -- prints: 20
print(foo["z"]) -- prints: 30

Note

For the following vector types, only the following keys are valid:

Vector Type Valid Keys
vector2 1, 2, x, y
vector3 1, 2, 3, x, y, z
vector4 1, 2, 3, 4, x, y, z, w

Parameters

Returns

The vector's element as a number.

Errors

__newindex

The __newindex metamethod permits vector element setting.

Vectors can be indexed with 1-based integer keys:

local foo = luacml.vector2()
foo[1] = 10

Or with case-insensitive "x", "y", "z", or "w" string keys:

local foo = luacml.vector3()
foo.x = 10
foo.Y = 20
foo["z"] = 30

Note

For the following vector types, only the following keys are valid:

Vector Type Valid Keys
vector2 1, 2, x, y
vector3 1, 2, 3, x, y, z
vector4 1, 2, 3, 4, x, y, z, w

Parameters

Returns

(None)

Errors

__tostring

Vectors can be converted to strings for easy printing.

local foo = luacml.vector2(1,2)
print(foo) -- prints: vector2:<1,2>

local foo = luacml.vector4(1,2,3,4)
print(foo) -- prints: vector4:<1,2,3,4>

Note

This function internally uses lua_pushfstring to format the output, so be aware of different formatting across versions of Lua.

Parameters

A vector.

Returns

The vector formatted as a string.

Errors

(None)

__unm

The negative of a vector can be generated.

local foo = luacml.vector3(1,2,-3)
print(-foo) -- prints: vector3:<-1,-2,3>

Note

The original vector is unchanged.

Parameters

A vector.

Returns

A new vector representing the negative of the original.

Errors

(None)

__add

Two vectors can be added together.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(3,2,1)
print(foo + bar) -- prints: vector3<4,4,4>

Note

The original vectors are unchanged.

Parameters

Two vectors of same type.

Returns

A new vector representing the element-wise sum.

Errors

__sub

Two vectors can be subtracted.

local foo = luacml.vector3(1,2,3)
local bar = luacml.vector3(3,2,1)
print(foo - bar) -- prints: vector3<-2,0,2>

Note

The original vectors are unchanged.

Parameters

Two vectors of same type.

Returns

A new vector representing the element-wise difference.

Errors

__mul

Vectors can be scaled.

local foo = luacml.vector3(1,2,3)
print(2.0 * foo) -- prints: vector3<2,4,6>
print(foo * 3.0) -- prints: vector3<3,6,9>

Note

The original vector is unchanged.

Parameters

A vector and a number, in either order.

Returns

A new vector representing the element-wise scale.

Errors

__div

Vectors can be inverse divided.

local foo = luacml.vector3(2,4,6)
print(foo / 2.0) -- prints: vector3<1,2,3>

Note

The original vector is unchanged.

Parameters

A vector and a number.

Returns

A new vector representing the element-wise division.

Errors

__eq

Vectors can be compared.

local foo = luacml.vector3(2,4,6)
local bar = luacml.vector3(2,4,6)
print(foo == bar) -- prints: true

Note

The original vectors are unchanged.

Parameters

Two vectors of same type.

Returns

Boolean represent element-wise equality.

Errors