Vector

Reference ❯ Vector and Matrix Types

2D Vector

vec2 top ↑

Syntax

vec2.x
vec2.y

myVec = vec2( 2.5, 10.0 )

-- Supports operators:
--   v = vec2 + vec2
--   v = vec2 - vec2
--   v = vec2 * scalar
--   v = vec2 / scalar
--   v = -vec2
--   b = vec2 == vec2
--   print( vec2 )

This type represents a 2D vector. Most mathematical operators such as equality, addition, subtraction, multiplication and division are provided, so you can use vec2 data types similarly to how you use numerical types. In addition there are a number of methods, such as v:dot( vec2 ) that can be called on vec2 types, please see the related items below.

x

float, the x component of this vec2

y

float, the y component of this vec2

Examples

--Some vector operations v1 = vec2( 1, 1 ) v2 = vec2( 4, 2 ) --Angle between v1:angleBetween( v2 ) --Adding v3 = v1 + v2 --Multiplying v4 = v1 * 5.0 --Rotating by 45 degrees v5 = v1:rotate(math.rad(45))

vec2.dot( v ) top ↑

Syntax

v1 = vec2( 1, 1 )
x = v1:dot( v )

This method returns the scalar dot product between two vec2 types

v

compute the dot product with this vec2 and v

Returns

Dot product between this vec2 and v

vec2.normalize() top ↑

Syntax

v1 = vec2( 5, 5 )
v1 = v1:normalize()

This method returns a normalized version of the vector

Returns

Normalized version of this vec2

vec2.dist( v ) top ↑

Syntax

v1 = vec2( 1, 1 )
x = v1:dist( vec2(2, 2) )

This method returns the distance between two vec2 types

v

compute the distance between this vec2 and v

Returns

Distance between this vec2 and v

vec2.distSqr( v ) top ↑

Syntax

v1 = vec2( 1, 1 )
x = v1:distSqr( vec2(2, 2) )

This method returns the squared distance between two vec2 types

v

compute the squared distance between this vec2 and v

Returns

Squared distance between this vec2 and v

vec2.len() top ↑

Syntax

v1 = vec2( 2, 1 )
x = v1:len()

This method returns the length of a vec2

Returns

Length of this vec2

vec2.lenSqr() top ↑

Syntax

v1 = vec2( 2, 1 )
x = v1:lenSqr()

This method returns the squared length of a vec2

Returns

Squared length of this vec2

vec2.cross( v ) top ↑

Syntax

v1 = vec2( 1, 1 )
v2 = v1:cross( vec2(2, 2) )

This method returns the cross product between two vec2 types

v

compute the cross product of this vec2 and v

Returns

Cross product of this vec2 and v

vec2.rotate( angle ) top ↑

Syntax

v1 = vec2( 1, 1 )
v1 = v1:rotate( math.rad(45) )

This method returns a rotated copy of a vec2 type. The angle is assumed to be radians.

angle

float, rotate this vector by angle in radians

Returns

Rotated version of this vec2

vec2.rotate90() top ↑

Syntax

v1 = vec2( 1, 1 )
v1 = v1:rotate90()

This method returns a copy of a vec2 type, rotated 90 degrees.

Returns

Rotated version of this vec2

vec2.angleBetween( v ) top ↑

Syntax

v1 = vec2( 1, 1 )
angle = math.deg( v1:angleBetween( vec2(5, 2) ) )

This method returns the angle between this vec2 and v in radians.

v

compute the angle between this vec2 and v

Returns

Angle between vec2 and v in radians

vec2.unpack() top ↑

Syntax

v = vec2( 1, 2 )
x,y = v:unpack()

This method returns each of a vector's components as separate values. It is useful for inputting vector types into functions which accept scalar values.

Examples

pos = vec2(20, 50) translate( pos:unpack() )

Returns

Two values x, y

3D Vector

vec3 top ↑

Syntax

vec3.x
vec3.y
vec3.z

myVec = vec3( 1.0, 2.0, 3.0 )
v = vec3(1,2,3) + vec3(3,2,1)
v = vec3(1,1,1) * 5

This type represents a 3D vector. Most mathematical operators such as equality, addition, subtraction, multiplication and division are provided, so you can use vec3 data as you would normally use numerical types. In addition there are a number of methods, such as v:dot( vec3 ) that can be called on vec3 types, please see the related items below.

x

float, x dimension of this vector

y

float, y dimension of this vector

z

float, z dimension of this vector

vec3.dot( v ) top ↑

Syntax

v1 = vec3( 1, 1, 1 )
x = v1:dot( v )

This method returns the scalar dot product between two vec3 types

v

compute the dot product with this vec3 and v

Returns

Dot product between this vec3 and v

vec3.normalize() top ↑

Syntax

v1 = vec3( 5, 5, 5 )
v1 = v1:normalize()

This method returns a normalized version of the vector

Returns

Normalized version of this vec3

vec3.dist( v ) top ↑

Syntax

v1 = vec3( 1, 1, 1 )
x = v1:dist( vec3(2, 2, 2) )

This method returns the distance between two vec3 types

v

compute the distance between this vec3 and v

Returns

Distance between this vec3 and v

vec3.distSqr( v ) top ↑

Syntax

v1 = vec3( 1, 1, 1 )
x = v1:distSqr( vec3(2, 2, 2) )

This method returns the squared distance between two vec3 types

v

compute the squared distance between this vec3 and v

Returns

Squared distance between this vec3 and v

vec3.len() top ↑

Syntax

v1 = vec3( 2, 1, 0 )
x = v1:len()

This method returns the length of a vec3

Returns

Length of this vec3

vec3.lenSqr() top ↑

Syntax

v1 = vec3( 2, 1, 0 )
x = v1:lenSqr()

This method returns the squared length of a vec3

Returns

Squared length of this vec3

vec3.cross( v ) top ↑

Syntax

v1 = vec3( 1, 1 )
v2 = v1:cross( vec3(2, 2) )

This method returns the cross product between two vec3 types

v

compute the cross product of this vec3 and v

Returns

Cross product of this vec3 and v

vec3.unpack() top ↑

Syntax

v = vec3( 1, 2, 3 )
x,y,z = v:unpack()

This method returns each of a vector's components as separate values. It is useful for inputting vector types into functions which accept scalar values.

Examples

myColor = vec3(255, 0, 255) background( myColor:unpack() )

Returns

Three values x, y, z

4D Vector

vec4 top ↑

Syntax

vec4.x
vec4.y
vec4.z
vec4.w

vec4.r
vec4.g
vec4.b
vec4.a

myVec = vec4( 1.0, 2.0, 3.0, 1.0 )
v = vec4(1,2,3,0) + vec4(3,2,1,1)
v = vec4(1,1,1,1) * 5

This type represents a 4D vector. Most mathematical operators such as equality, addition, subtraction, multiplication and division are provided, so you can use vec3 data as you would normally use numerical types. In addition there are a number of methods, such as v:dot( vec4 ) that can be called on vec4 types, please see the related items below.

x

float, x dimension of this vector

y

float, y dimension of this vector

z

float, z dimension of this vector

w

float, w dimension of this vector

vec4.dot( v ) top ↑

Syntax

v1 = vec4( 1, 1, 1, 1 )
x = v1:dot( v )

This method returns the scalar dot product between two vec4 types

v

compute the dot product with this vec4 and v

Returns

Dot product between this vec4 and v

vec4.normalize() top ↑

Syntax

v1 = vec4( 5, 5, 5, 5 )
v1 = v1:normalize()

This method returns a normalized version of the vector

Returns

Normalized version of this vec4

vec4.dist( v ) top ↑

Syntax

v1 = vec4( 1, 1, 1, 1 )
x = v1:dist( vec4(2, 2, 2, 2) )

This method returns the distance between two vec4 types

v

compute the distance between this vec4 and v

Returns

Distance between this vec4 and v

vec4.distSqr( v ) top ↑

Syntax

v1 = vec4( 1, 1, 1, 1 )
x = v1:distSqr( vec4(2, 2, 2, 2) )

This method returns the squared distance between two vec4 types

v

compute the squared distance between this vec4 and v

Returns

Squared distance between this vec4 and v

vec4.len() top ↑

Syntax

v1 = vec4( 2, 1, 0, 0 )
x = v1:len()

This method returns the length of a vec4

Returns

Length of this vec4

vec4.lenSqr() top ↑

Syntax

v1 = vec4( 2, 1, 0, 0 )
x = v1:lenSqr()

This method returns the squared length of a vec4

Returns

Squared length of this vec4

vec4.unpack() top ↑

Syntax

v = vec4( 1, 2, 3, 4 )
x,y,z,w = v:unpack()

This method returns each of a vector's components as separate values. It is useful for inputting vector types into functions which accept scalar values.

Examples

myColor = vec4(255, 0, 255, 255) background( myColor:unpack() )

Returns

Four values x, y, z, w

Matrix

matrix top ↑

Syntax

matrix[1] ... matrix[16]
m = matrix()
m = matrix(1, 2, 3, ... 16)
m = matrix1 * matrix2

This type represents a 4x4 column-major matrix. This matrix type is used to represent transformations in Codea, and can be used with functions such as modelMatrix() and viewMatrix(). The matrix type supports the following arithmetic operators: multiplication (between two matrices), multiplication by scalar, division by scalar, equality, and element-wise addition and subtraction.

Because this type is used to represent transformations it also provides a number of 3D transformation methods such as matrix:translate(x,y,z), matrix:rotate(angle,x,y,z). See the related items for a full list.

Constructing a matrix with no parameters returns the identity matrix. Passing 16 numbers when constructing a matrix will assign those values to the elements of the matrix. Individual matrix elements can be accessed by their index, for example m[1] for the first element and m[16] for the last element. Entries are defined such that the x,y,z translation components are stored in elements 13, 14, and 15 respectively.

element

float, an element of the matrix

Examples

matrix[x] = y m1 = matrix( 1,2,3, ... ,16 ) m2 = matrix( 4,5,6, ... ,20 ) -- Supports operators: m = m1 * m2 m = m1 + m2 m = m1 - m2 m = m1 * 10 m = m1 / 10 m = -m1 checkEqual = m1 == m2 print( m1 )

Returns

A new matrix with the given elements

matrix.rotate( m, r, x, y, z ) top ↑

Syntax

rotated = m:rotate( angle, axisX, axisY, axisZ )

This method returns the matrix multiplied by a rotation matrix defining a rotation of angle degrees around the x,y,z axis or (0,0,1) if no axis is given.

angle

float, the rotation in degrees

axisX

float, the x component of the axis of rotation

axisY

float, the y component of the axis of rotation

axisZ

float, the z component of the axis of rotation

Examples

m = matrix() --Rotate about 0,0,1 rotated = m:rotate(30) --Rotate by a given axis rotated= m:rotate(30, 1, 0, 0)

Returns

A matrix which rotates m by the specified rotation

matrix.translate( m, x, y, z ) top ↑

Syntax

translated = m:translate( x, y, z )

This method returns the matrix multiplied by a translation matrix defining a translation of x, y, z.

x

float, the x component of translation

y

float, the y component of translation

z

float, optional (defaults to 0) the z component of translation"

Examples

m = matrix() translated = m:translate(100,20,10)

Returns

A matrix which translates m by the specified amount

matrix.scale( m, x, y, z ) top ↑

Syntax

scaled = m:scale( x, y, z )

This method returns the matrix scaled by a translation matrix defining a scaling to each axis.

x

float, the x component of scale, or the uniform scale if no other components are given

y

float, optional, the y component of scale

z

float, optional, defaults to 1 if x and y are both given, otherwise x – the z component of scale

Examples

m = matrix() s = m:scale(100,20,10) --Uniform scaling s = m:scale(5)

Returns

A matrix which scales m by the specified amount

matrix.inverse( m ) top ↑

Syntax

inv = m:inverse()

This method returns the inverse of the given matrix, if such an inverse exists. If no inverse exists, the result is a matrix of NaN values. The inverse of a matrix is a matrix such that m * mInv = I, where I is the identity matrix.

m

the matrix to invert

Returns

A matrix which inverts m

matrix.transpose( m ) top ↑

Syntax

transposed = m:transpose()

This method returns the transpose of the given matrix. The transpose of a matrix is a matrix that is flipped on the major diagonal (ie, elements 1,6,11,16). For example element 2 and element 5 are swapped, etc.

m

the matrix to transpose

Returns

A matrix which is the transpose of m

matrix.determinant( m ) top ↑

Syntax

det = m:determinant()

This method returns the determinant of the given matrix. This has various uses for determining characteristics of a matrix, especially whether it is invertible or not.

Returns

A float equal to the determinant of m