 # 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

## Bounds

### boundstop ↑

#### Syntax

```b = bounds(min, max)
b = bounds(vec3(0, 0, 0), vec3(1, 1, 1))
```

A geometric utility type representing the rectangular bounding volume. Create a new bounds by giving it a minimum and maximum range as `vec3`s

 min vec3, the minimum x,y,z range of the area encapsulated by the bounding volume max vec3, the maximum x,y,z range of the area encapsulated by the bounding volume valid boolean, whether or not this bounds is valid (i.e. has zero or greater volume) center vec3, the center of the volume (i.e. half way between `min` and `max`) offset vec3, the offset of the volume (i.e. `min`) size vec3, the size of the volume (i.e. `max - min`)

### bounds.intersects()top ↑

#### Syntax

```bounds.intersects(other)
bounds.intersects(origin, dir)
```

This method has two variants, the first `bounds.intersects(other)` checks to see whether two bounds values intersect

The second form, `bounds.intersects(origin, dir)` returns `true` if the given ray (specified by `origin`, `dir` intersects the bounds

 other bounds, another bounds value to test for intersection with origin vec3, point defining the origin of the ray to test for intersection with dir vec3, vector describing the ray to test for intersection with

#### Returns

boolean, whether this bounding volume intersects another or the given ray

### bounds.encapsulate()top ↑

#### Syntax

```bounds.encapsulate(point)
```

This will expand the current bounds to include the given `point` (vec3)

 point vec3, the bounds will be extended to enclose this point

### bounds.translate()top ↑

#### Syntax

```bounds.translate(offset)
```

Translate (move) the bounds by the specified `offset`

 offset vec3, the bounds will offset by this amount

### bounds.set()top ↑

#### Syntax

```bounds.set(min, max)
```

Reset the bounds using the specified `min` and `max` values

 min vec3, the minimum x,y,z range of the area encapsulated by the bounding volume max vec3, the maximum x,y,z range of the area encapsulated by the bounding volume

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