 # Vector

## 2D Vector

### vec2top ↑

#### 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 )
```

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() )

Two values x, y

## 3D Vector

### vec3top ↑

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

### vec4top ↑

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

### matrixtop ↑

#### Syntax

```matrix ... matrix
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` for the first element and `m` 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

## Quaternion

### quattop ↑

#### Syntax

```quat.x
quat.y
quat.z
quat.w

myQuat = quat.eulerAngles(45,45,45)
```

This type represents a quaternion.

 x float, x dimension of this quaternion y float, y dimension of this quaternion z float, z dimension of this quaternion w float, w dimension of this quaternion

### quat.eulerAngles( x, y, z )top ↑

#### Syntax

```q = quat.eulerAngles(45,0,45)
```

Creates a new quaternion using 3 euler angles given in degrees.

 x float, the amount of pitch in degrees y float, the amount of roll in degrees z float, the amount of yaw in degrees

#### Returns

The resulting quaternion

### quat.angleAxis( angle, axis )top ↑

#### Syntax

```q = quat.angleAxis(45, vec3(0,0,1))
```

Creates a new quaternion using an angle and axis.

 angle float, the amount of rotation about the axis in degrees axis vec3, the axis to rotate around

#### Returns

The resulting quaternion

### quat.lookRotation( forward, up )top ↑

#### Syntax

```q = quat.lookRotation( vec3(0,0,1), vec3(0,1,0) )
```

Creates a new quaternion that 'looks' in a specified direction.

 forward vec3, the direction to look at up vec3, the upwards direction used to orient the quaternion

#### Returns

The resulting quaternion

### quat.fromToRotation( from, to )top ↑

#### Syntax

```q = quat.fromToRotation( vec3(0,0,1), vec3(1,0,0) )
```

Creates a new quaternion that rotates between two directions.

 from vec3, the start direction to vec3, the the end direction

#### Returns

The resulting quaternion

### quat.slerp( q, t )top ↑

#### Syntax

```q1 = quat.eulerAngles(0,0,0)
q2 = quat.eulerAngles(0,0,90)
q3 = q1:slerp(p2, 0.5)
```

Performs spherical interpolation (slerp) from this quaternion to another.

 t float, the amount of interpolation to perform

#### Returns

The spherically interpolated quaternion

### quat.angles()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
angles = q:angles()
```

Extracts the euler angles from a quaternion and returns them as a vec3 in degrees.

#### Returns

vec3, the euler angles for this quaternion in degrees

### quat.normalized()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
nq = q:normalized()
```

Returns a normalized copy of this quaternion

#### Returns

quat, a normalized version of this quaternion

### quat.normalize()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
q:normalize()
```

Normalize this quaternion

### quat.conjugate()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
cq = q:conjugate()
```

Return the conjugation of this quaternion

#### Returns

quat, a conjugated version of this quaternion

### quat.len()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
len = q:len()
```

Return the length of this quaternion

#### Returns

float, the length of this quaternion

### quat.lenSqr()top ↑

#### Syntax

```q = quat.eulerAngles(20,30,40)
len2 = q:lenSqr()
```

Return the squared length of this quaternion

#### Returns

float, the squared length of this quaternion