`nupp.math.quat`

Three-dimensional rotation operations over (x, y, z, w) number quadruples.

Module contents

Functions

Function	Kind	Description
`add`	function	Adds two rotations componentwise.
`basis`	function	Returns a unit rotation's three-by-three matrix in column-major order.
`conjugate`	function	Returns the rotation undoing a unit one.
`dot`	function	Returns the four-component dot product, the cosine of half the angle between two unit rotations.
`fromAxisAngle`	function	Builds a rotation of an angle about an axis.
`fromTo`	function	Returns the shortest rotation carrying one direction onto another.
`identity`	function	Returns the rotation that turns nothing.
`inverse`	function	Returns the rotation undoing any non-zero one, or the identity for zero.
`length`	function	Returns the length, which is one for a unit rotation.
`lengthSquared`	function	Returns the squared length, which is one for a unit rotation.
`multiply`	function	Composes two rotations, applying the second one first.
`nlerp`	function	Interpolates between two unit rotations the short way around, blending components rather than the arc.
`normalize`	function	Returns a unit rotation in the same direction, or the identity for zero.
`rotate`	function	Turns a vector by a unit rotation.
`scale`	function	Multiplies every component by a factor.
`slerp`	function	Interpolates between two unit rotations the short way around at a constant angular speed.
`sub`	function	Subtracts the second rotation from the first componentwise.
`toAxisAngle`	function	Recovers the axis and angle of a unit rotation.
`toMatrix`	function	Writes a unit rotation as a four-by-four column-major matrix without translation.

Functions#

`add`function#

local add: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number
): (number, number, number, number)

Adds two rotations componentwise.

Arguments

Name	Type	Description
`ax`	`number`	the first rotation's x component
`ay`	`number`	the first rotation's y component
`az`	`number`	the first rotation's z component
`aw`	`number`	the first rotation's w component
`bx`	`number`	the second rotation's x component
`by`	`number`	the second rotation's y component
`bz`	`number`	the second rotation's z component
`bw`	`number`	the second rotation's w component

Returns

Type	Description
`number`	the sum's x component
`number`	the sum's y component
`number`	the sum's z component
`number`	the sum's w component

`basis`function#

local basis: function(
    x: number,
    y: number,
    z: number,
    w: number
): (number, number, number, number, number, number, number, number, number)

Returns a unit rotation's three-by-three matrix in column-major order.

Answered rather than written, for the caller folding a rotation into something larger. toMatrix is the form for storage.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the first column's x component
`number`	the first column's y component
`number`	the first column's z component
`number`	the second column's x component
`number`	the second column's y component
`number`	the second column's z component
`number`	the third column's x component
`number`	the third column's y component
`number`	the third column's z component

`conjugate`function#

local conjugate: function(x: number, y: number, z: number, w: number): (number, number, number, number)

Returns the rotation undoing a unit one.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the conjugate's x component
`number`	the conjugate's y component
`number`	the conjugate's z component
`number`	the conjugate's w component

`dot`function#

local dot: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number
): number

Returns the four-component dot product, the cosine of half the angle between two unit rotations.

Arguments

Name	Type	Description
`ax`	`number`	the first rotation's x component
`ay`	`number`	the first rotation's y component
`az`	`number`	the first rotation's z component
`aw`	`number`	the first rotation's w component
`bx`	`number`	the second rotation's x component
`by`	`number`	the second rotation's y component
`bz`	`number`	the second rotation's z component
`bw`	`number`	the second rotation's w component

Returns

Type	Description
`number`	the dot product

`fromAxisAngle`function#

local fromAxisAngle: function(x: number, y: number, z: number, radians: number): (number, number, number, number)

Builds a rotation of an angle about an axis.

The axis is normalized here, so it need not arrive as a unit vector.

Arguments

Name	Type	Description
`x`	`number`	the axis's x component
`y`	`number`	the axis's y component
`z`	`number`	the axis's z component
`radians`	`number`	the turn about the axis, counter-clockwise looking down it

Returns

Type	Description
`number`	the rotation's x component, or zero for a zero axis
`number`	the rotation's y component, or zero for a zero axis
`number`	the rotation's z component, or zero for a zero axis
`number`	the rotation's w component, or one for a zero axis

`fromTo`function#

local fromTo: function(
    ax: number,
    ay: number,
    az: number,
    bx: number,
    by: number,
    bz: number
): (number, number, number, number)

Returns the shortest rotation carrying one direction onto another.

Neither direction has to be a unit vector. Opposed directions have no shortest rotation, so one half turn across them is chosen.

Arguments

Name	Type	Description
`ax`	`number`	the starting direction's x component
`ay`	`number`	the starting direction's y component
`az`	`number`	the starting direction's z component
`bx`	`number`	the target direction's x component
`by`	`number`	the target direction's y component
`bz`	`number`	the target direction's z component

Returns

Type	Description
`number`	the rotation's x component, or zero for a zero direction
`number`	the rotation's y component, or zero for a zero direction
`number`	the rotation's z component, or zero for a zero direction
`number`	the rotation's w component, or one for a zero direction

`identity`function#

local identity: function(): (number, number, number, number)

Returns the rotation that turns nothing.

Returns

Type	Description
`number`	the identity x component, zero
`number`	the identity y component, zero
`number`	the identity z component, zero
`number`	the identity w component, one

`inverse`function#

local inverse: function(x: number, y: number, z: number, w: number): (number, number, number, number)

Returns the rotation undoing any non-zero one, or the identity for zero.

conjugate is this for a unit rotation and is cheaper; this one is also correct for a rotation whose length has drifted from one.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the inverse's x component, or zero for a zero rotation
`number`	the inverse's y component, or zero for a zero rotation
`number`	the inverse's z component, or zero for a zero rotation
`number`	the inverse's w component, or one for a zero rotation

`length`function#

local length: function(x: number, y: number, z: number, w: number): number

Returns the length, which is one for a unit rotation.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the length

`lengthSquared`function#

local lengthSquared: function(x: number, y: number, z: number, w: number): number

Returns the squared length, which is one for a unit rotation.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the squared length

`multiply`function#

local multiply: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number
): (number, number, number, number)

Composes two rotations, applying the second one first.

The order matches column-major matrix multiplication, so the matrix of multiply(a, b) is the matrix of a times the matrix of b.

Arguments

Name	Type	Description
`ax`	`number`	the second-applied rotation's x component
`ay`	`number`	the second-applied rotation's y component
`az`	`number`	the second-applied rotation's z component
`aw`	`number`	the second-applied rotation's w component
`bx`	`number`	the first-applied rotation's x component
`by`	`number`	the first-applied rotation's y component
`bz`	`number`	the first-applied rotation's z component
`bw`	`number`	the first-applied rotation's w component

Returns

Type	Description
`number`	the composition's x component
`number`	the composition's y component
`number`	the composition's z component
`number`	the composition's w component

`nlerp`function#

local nlerp: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number,
    t: number
): (number, number, number, number)

Interpolates between two unit rotations the short way around, blending components rather than the arc.

Cheaper than slerp and not constant in angular speed. If the short route ends at -b, that endpoint form is kept through t == 1 so the four components stay continuous.

Arguments

Name	Type	Description
`ax`	`number`	the starting rotation's x component
`ay`	`number`	the starting rotation's y component
`az`	`number`	the starting rotation's z component
`aw`	`number`	the starting rotation's w component
`bx`	`number`	the ending rotation's x component
`by`	`number`	the ending rotation's y component
`bz`	`number`	the ending rotation's z component
`bw`	`number`	the ending rotation's w component
`t`	`number`	the interpolation factor

Returns

Type	Description
`number`	the interpolated x component
`number`	the interpolated y component
`number`	the interpolated z component
`number`	the interpolated w component

`normalize`function#

local normalize: function(x: number, y: number, z: number, w: number): (number, number, number, number)

Returns a unit rotation in the same direction, or the identity for zero.

The sign is left alone: q and -q are the same rotation, and which one arrived is not canonicalized away.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the normalized x component, or zero for a zero rotation
`number`	the normalized y component, or zero for a zero rotation
`number`	the normalized z component, or zero for a zero rotation
`number`	the normalized w component, or one for a zero rotation

`rotate`function#

local rotate: function(
    qx: number,
    qy: number,
    qz: number,
    qw: number,
    x: number,
    y: number,
    z: number
): (number, number, number)

Turns a vector by a unit rotation.

Cheaper than building a matrix for a handful of vectors and dearer for many, where basis amortizes its nine products across every vector after the first.

Arguments

Name	Type	Description
`qx`	`number`	the rotation's x component
`qy`	`number`	the rotation's y component
`qz`	`number`	the rotation's z component
`qw`	`number`	the rotation's w component
`x`	`number`	the vector's x component
`y`	`number`	the vector's y component
`z`	`number`	the vector's z component

Returns

Type	Description
`number`	the turned x component
`number`	the turned y component
`number`	the turned z component

`scale`function#

local scale: function(x: number, y: number, z: number, w: number, factor: number): (number, number, number, number)

Multiplies every component by a factor.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component
`factor`	`number`	the scaling factor

Returns

Type	Description
`number`	the scaled x component
`number`	the scaled y component
`number`	the scaled z component
`number`	the scaled w component

`slerp`function#

local slerp: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number,
    t: number
): (number, number, number, number)

Interpolates between two unit rotations the short way around at a constant angular speed.

Nearly parallel endpoints fall back to nlerp, whose answer they agree on where the arc the spherical form divides by has vanished. If the short route ends at -b, that endpoint form is kept through t == 1 so the four components stay continuous.

Arguments

Name	Type	Description
`ax`	`number`	the starting rotation's x component
`ay`	`number`	the starting rotation's y component
`az`	`number`	the starting rotation's z component
`aw`	`number`	the starting rotation's w component
`bx`	`number`	the ending rotation's x component
`by`	`number`	the ending rotation's y component
`bz`	`number`	the ending rotation's z component
`bw`	`number`	the ending rotation's w component
`t`	`number`	the interpolation factor

Returns

Type	Description
`number`	the interpolated x component
`number`	the interpolated y component
`number`	the interpolated z component
`number`	the interpolated w component

`sub`function#

local sub: function(
    ax: number,
    ay: number,
    az: number,
    aw: number,
    bx: number,
    by: number,
    bz: number,
    bw: number
): (number, number, number, number)

Subtracts the second rotation from the first componentwise.

Arguments

Name	Type	Description
`ax`	`number`	the first rotation's x component
`ay`	`number`	the first rotation's y component
`az`	`number`	the first rotation's z component
`aw`	`number`	the first rotation's w component
`bx`	`number`	the second rotation's x component
`by`	`number`	the second rotation's y component
`bz`	`number`	the second rotation's z component
`bw`	`number`	the second rotation's w component

Returns

Type	Description
`number`	the difference's x component
`number`	the difference's y component
`number`	the difference's z component
`number`	the difference's w component

`toAxisAngle`function#

local toAxisAngle: function(x: number, y: number, z: number, w: number): (number, number, number, number)

Recovers the axis and angle of a unit rotation.

The angle lands in [0, 2pi] rather than being folded into [0, pi], so q and -q answer the two opposite ways around the same rotation.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component

Returns

Type	Description
`number`	the axis's x component, or one for the identity
`number`	the axis's y component, or zero for the identity
`number`	the axis's z component, or zero for the identity
`number`	the turn about the axis in radians, zero for positive identity or `2pi` for negative identity

`toMatrix`function#

local toMatrix: function(x: number, y: number, z: number, w: number, out: {number}, offset: integer): nil

Writes a unit rotation as a four-by-four column-major matrix without translation.

The sixteen numbers start at offset, which indexes the first of them. The layout is the one a GPU expects, so an uploaded destination is written in place rather than repacked.

Arguments

Name	Type	Description
`x`	`number`	the rotation's x component
`y`	`number`	the rotation's y component
`z`	`number`	the rotation's z component
`w`	`number`	the rotation's w component
`out`	`{number}`	the destination the sixteen numbers are written to
`offset`	`integer`	the index the first number is written at

Returns

Type	Description
`nil`	The operation returns no value.

nupp.math.quat

Module contents

Functions

Functions#

addfunction#

Arguments

Returns

basisfunction#

Arguments

Returns

conjugatefunction#

Arguments

Returns

dotfunction#

Arguments

Returns

fromAxisAnglefunction#

Arguments

Returns

fromTofunction#

Arguments

Returns

identityfunction#

Returns

inversefunction#

Arguments

Returns

lengthfunction#

Arguments

Returns

lengthSquaredfunction#

Arguments

Returns

multiplyfunction#

Arguments

Returns

nlerpfunction#

Arguments

Returns

normalizefunction#

Arguments

Returns

rotatefunction#

Arguments

Returns

scalefunction#

Arguments

Returns

slerpfunction#

Arguments

Returns

subfunction#

Arguments

Returns

toAxisAnglefunction#

Arguments

Returns

toMatrixfunction#

Arguments

Returns

`nupp.math.quat`

`add`function#

`basis`function#

`conjugate`function#

`dot`function#

`fromAxisAngle`function#

`fromTo`function#

`identity`function#

`inverse`function#

`length`function#

`lengthSquared`function#

`multiply`function#

`nlerp`function#

`normalize`function#

`rotate`function#

`scale`function#

`slerp`function#

`sub`function#

`toAxisAngle`function#

`toMatrix`function#