# `nupp.math.quat` Three-dimensional rotation operations over `(x, y, z, w)` number quadruples. ## Functions ### `add` _function_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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_ ```nupp 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. |