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

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