lin

package
v0.21.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 12, 2024 License: BSD-2-Clause Imports: 2 Imported by: 13

Documentation

Overview

Package lin provides a linear math library intended for games. It includes vectors, matrices, quaternions, transforms, and some useful constants and utility functions.

Package lin is provided as part of the vu (virtual universe) 3D engine.

Index

Constants

View Source 
const (

	// PI and its commonly needed variants.
	PI     float64 = math.Pi
	PIx2   float64 = PI * 2
	HalfPi float64 = PIx2 * 0.25
	DegRad float64 = PIx2 / 360.0 // X degrees * DEG_RAD = Y radians
	RadDeg float64 = 360.0 / PIx2 // Y radians * RAD_DEG = X degrees

	// Convenience numbers.
	Large float64 = math.MaxFloat32
	Sqrt2 float64 = math.Sqrt2
	Sqrt3 float64 = 1.73205

	// Epsilon is used to distinguish when a float is close enough to a number.
	// Wikipedia: "In set theory epsilon is the limit ordinal of the sequence..."
	Epsilon float64 = 0.000001
)

Various linear math constants.

Variables

View Source 
var M3I = &M3{
	1, 0, 0,
	0, 1, 0,
	0, 0, 1}

M3I provides a reference identity matrix that can be used in calculations. It should never be changed.

View Source 
var M3Z = &M3{
	0, 0, 0,
	0, 0, 0,
	0, 0, 0}

M3Z provides a reference zero matrix that can be used in calculations. It should never be changed.

View Source 
var M4I = &M4{
	1, 0, 0, 0,
	0, 1, 0, 0,
	0, 0, 1, 0,
	0, 0, 0, 1}

M4I provides a reference identity matrix that can be used in calculations. It should never be changed.

View Source 
var M4Z = &M4{
	0, 0, 0, 0,
	0, 0, 0, 0,
	0, 0, 0, 0,
	0, 0, 0, 0}

M4Z provides a reference zero matrix that can be used in calculations. It should never be changed.

View Source 
var QI = &Q{0, 0, 0, 1}

QI provides a reference identity matrix that can be used in calculations. It should never be changed.

Functions

func AbsMax 

func AbsMax(a0, a1, a2, a3 float64) int

AbsMax returns the index of the largest absolute value of the 4 given values. The returned index is always from 0-3.

func Aeq 

func Aeq(a, b float64) bool

Aeq (~=) almost-equals returns true if the difference between a and b is so small that it doesn't matter.

func AeqZ 

func AeqZ(x float64) bool

AeqZ (~=) almost-equals returns true if the difference between x and zero is so small that it doesn't matter.

func Atan2F 

func Atan2F(y, x float64) float64

Atan2F is a fast approximation of Atan2. Source was posted at: 

http://www.gamedev.net/topic/441464-manually-implementing-atan2-or-atan/

func Clamp 

func Clamp[T Number](v, min, max T) T

Clamp returns a scalar value (one of: s, lb, ub) guaranteed to be within the range given by lower bound lb and upper bound ub.

func Deg 

func Deg(rad float64) float64

Deg converts radians to degrees.

func Lerp 

func Lerp(a, b, ratio float64) float64

Lerp returns the linear interpolation of a to b by the given ratio.

func Max3 

func Max3(a, b, c float64) float64

Max3 returns the largest of the 3 numbers.

func Min3 

func Min3(a, b, c float64) float64

Min3 returns the smallest of the 3 numbers.

func MultSQ 

func MultSQ(x, y, z float64, q *Q) (vx, vy, vz float64)

MultSQ applies rotation q to scalar vector (x,y,z) The updated scalar vector (vx,vy,vz) is returned.

func Nang 

func Nang(radians float64) float64

Nang (normalize angle) ensures a rotation angle in radians is within the range [-PI, PI] (2PI*radians is 360 degrees).

func Rad 

func Rad(deg float64) float64

Rad converts degrees to radians.

func Round 

func Round(val float64, prec int) float64

Round return rounded version of x with prec precision. Special cases are: 

Round(±0) = ±0
Round(±Inf) = ±Inf
Round(NaN) = NaN

Types

type M3 

type M3 struct {
	Xx, Xy, Xz float64 // indices 0, 1, 2  [00, 01, 02]  X-Axis
	Yx, Yy, Yz float64 // indices 3, 4, 5  [10, 11, 12]  Y-Axis
	Zx, Zy, Zz float64 // indices 6, 7, 8  [20, 21, 22]  Z-Axis
}

M3 is a 3x3 matrix where the matrix elements are individually addressable.

func NewM3 

func NewM3() *M3

NewM3 creates a new, all zero, 3x3 matrix.

func NewM3I 

func NewM3I() *M3

NewM3I creates a new 3x3 identity matrix. 

[ 1 0 0 ]    [ Xx Xy Xz ]
[ 0 1 0 ] => [ Yx Yy Yz ]
[ 0 0 1 ]    [ Zx Zy Zz ]

func (*M3) Abs 

func (m *M3) Abs(a *M3) *M3

Abs updates m to be the the absolute (non-negative) element values of the corresponding element values in matrix a. The source matrix a is unchanged. The updated matrix m is returned.

func (*M3) Add 

func (m *M3) Add(a, b *M3) *M3

Add (+) adds matrices a and b storing the results in m. Each element of matrix b is added to the corresponding matrix a element. It is safe to use the calling matrix m as one or both of the parameters. For example the plus.equals operation (+=) is 

m.Add(m, b)

The updated matrix m is returned.

func (*M3) Adj 

func (m *M3) Adj(a *M3) *M3

Adj updates m to be the adjoint matrix of matrix a. The adjoint matrix is created by the transpose of the cofactor matrix of the original matrix. 

[ a.cof(0,0) a.cof(1,0) a.cof(2,0) ]    [ mXx mXy mXz ]
[ a.cof(0,1) a.cof(1,1) a.cof(2,1) ] => [ mYx mYy mYz ]
[ a.cof(0,2) a.cof(1,2) a.cof(2,2) ]    [ mZx mZy mZz ]

The updated matrix m is returned.

func (*M3) Aeq 

func (m *M3) Aeq(a *M3) bool

Aeq (~=) almost equals returns true if all the elements in matrix m have essentially the same value as the corresponding elements in matrix a. Used where equals is unlikely to return true due to float precision.

func (*M3) Cof 

func (m *M3) Cof(row, col int) float64

Cof returns one of the possible cofactors of a 3x3 matrix given the input minor (the row and column removed from the calculation). Wikipedia states: 

"cofactors [...] are useful for computing both the determinant
 and inverse of square matrices".

func (*M3) Det 

func (m *M3) Det() float64

Det returns the determinant of matrix m. Determinants are helpful when calculating the inverse of transform matrices. Wikipedia states: 

"The determinant provides important information about [..] a matrix that
 corresponds to a linear transformation of a vector space [..] the transformation
 has an inverse operation exactly when the determinant is nonzero."

func (*M3) Eq 

func (m *M3) Eq(a *M3) bool

Eq (==) returns true if all the elements in matrix m have the same value as the corresponding elements in matrix a.

func (*M3) Inv 

func (m *M3) Inv(a *M3) *M3

Inv updates m to be the inverse of matrix a. The updated matrix m is returned. Matrix m is not updated if the matrix has no inverse.

func (*M3) Mult 

func (m *M3) Mult(l, r *M3) *M3

Mult (*) multiplies matrices l and r storing the results in m. 

[ lXx lXy lXz ] [ rXx rXy rXz ]    [ mXx mXy mXz ]
[ lYx lYy lYz ]x[ rYx rYy rYz ] => [ mYx mYy mYz ]
[ lZx lZy lZz ] [ rZx rZy rZz ]    [ mZx mZy mZz ]

It is safe to use the calling matrix m as one or both of the parameters. For example (*=) is 

m.Mult(m, r)

The updated matrix m is returned.

func (*M3) MultLtR 

func (m *M3) MultLtR(lt, r *M3) *M3

MultLtR multiplies the transpose of matrix l on left of matrix r and stores the result in m. This can be used for saving a method call when calculating inverse transforms. 

[ lXx lYx lZx ] [ rXx rXy rXz ]    [ mXx mXy mXz ]
[ lXy lYy lZy ]x[ rYx rYy rYz ] => [ mYx mYy mYz ]
[ lXz lYz lZz ] [ rZx rZy rZz ]    [ mZx mZy mZz ]

It is safe to use the calling matrix m as one or both of the parameters. The updated matrix m is returned.

func (*M3) Scale 

func (m *M3) Scale(s float64) *M3

Scale (*) each element of matrix m by the given scalar. The updated matrix m is returned.

func (*M3) ScaleS 

func (m *M3) ScaleS(x, y, z float64) *M3

ScaleS (*) scales each column of matrix m using the corresponding scaler elements x, y, z. The updated matrix m is returned.

func (*M3) ScaleSM 

func (m *M3) ScaleSM(x, y, z float64) *M3

ScaleSM updates m to be the multiplication of a scale matrix created from x, y, z and itself. The updated matrix m is returned. 

[ x 0 0 ]   [ mXx mXy mXz ]    [ mXx' mXy' mXz' ]
[ 0 y 0 ] x [ mYx mYy mYz ] => [ mYx' mYy' mYz' ]
[ 0 0 z ]   [ mZx mZy mZz ]    [ mZx' mZy' mZz' ]

Be sure to pick the correct scale (SM or MS) when doing transforms.

func (*M3) ScaleV 

func (m *M3) ScaleV(v *V3) *M3

ScaleV (*) scales each column of matrix m using the given vector v for elements for x, y, z. The updated matrix m is returned.

func (*M3) Set 

func (m *M3) Set(a *M3) *M3

Set (=) assigns all the scaler values from matrix a to the corresponding scaler values in matrix m. The source matrix a is unchanged. The updated matrix m is returned.

func (*M3) SetAa 

func (m *M3) SetAa(ax, ay, az, ang float64) *M3

SetAa set axis-angle, updates m to be a rotation matrix from the given axis (ax, ay, az) and angle (in radians). See: 

http://en.wikipedia.org/wiki/Rotation_matrix#Rotation_matrix_from_axis_and_angle
http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q38 (*note column order)

The updated matrix m is returned.

func (*M3) SetM4 

func (m *M3) SetM4(a *M4) *M3

SetM4 (=) updates calling matrix m to be the 3x3 matrix from the top left corner of the given 4x4 matrix m4. The source matrix a is unchanged. The updated matrix m is returned. 

[ Xx Xy Xz Xw ]    [ Xx Xy Xz ]
[ Yx Yy Yz Yw ] => [ Yx Yy Yz ]
[ Zx Zy Zz Zw ]    [ Zx Zy Zz ]
[ Wx Wy Wz Ww ]

func (*M3) SetQ 

func (m *M3) SetQ(q *Q) *M3

SetQ converts a quaternion rotation representation to a matrix rotation representation. SetQ updates matrix m to be the rotation matrix representing the rotation described by unit-quaternion q. 

                   [ mXx mXy mXz ]
[ qx qy qz qw ] => [ mYx mYy mYz ]
                   [ mZx mZy mZz ]

The parameter q is unchanged. The updated matrix m is returned.

func (*M3) SetS 

func (m *M3) SetS(Xx, Xy, Xz, Yx, Yy, Yz, Zx, Zy, Zz float64) *M3

SetS (=) explicitly sets the matrix scaler values using the given scalers. The source matrix a is unchanged. The updated matrix m is returned. 

Xx, Xy, Xz is the X Axis.
Yx, Yy, Yz is the Y Axis.
Zx, Zy, Zz is the Z Axis.

func (*M3) SetSkewSym 

func (m *M3) SetSkewSym(v *V3) *M3

SetSkewSym sets the matrix m to be a skew-symetric matrix based on the elements of vector v. Wikipedia states: 

"A skew-symmetric matrix is a square matrix
 whose transpose is also its negative."

func (*M3) Sub 

func (m *M3) Sub(a, b *M3) *M3

Sub (-) subtracts matrices b from a storing the results in m. Each element of matrix b is subtracted from the corresponding matrix a element. It is safe to use the calling matrix m as one or both of the parameters. For example the minus.equals operation (-=) is 

m.Sub(m, b)

The updated matrix m is returned.

func (*M3) Transpose 

func (m *M3) Transpose(a *M3) *M3

Transpose updates m to be the reflection of matrix a over its diagonal. This essentially changes row-major order to column-major order or vice-versa. 

[ Xx Xy Xz ]    [ Xx Yx Zx ]
[ Yx Yy Yz ] => [ Xy Yy Zy ]
[ Zx Zy Zz ]    [ Xz Yz Zz ]

The input matrix a is not changed. Matrix m may be used as the input parameter. The updated matrix m is returned.

type M4 

type M4 struct {
	Xx, Xy, Xz, Xw float64 // indices 0, 1, 2, 3  [00, 01, 02, 03] X-Axis
	Yx, Yy, Yz, Yw float64 // indices 4, 5, 6, 7  [10, 11, 12, 13] Y-Axis
	Zx, Zy, Zz, Zw float64 // indices 8, 9, a, b  [20, 21, 22, 23] Z-Axis
	Wx, Wy, Wz, Ww float64 // indices c, d, e, f  [30, 31, 32, 33]
}

M4 is a 4x4 matrix where the matrix elements are individually addressable.

func NewM4 

func NewM4() *M4

NewM4 creates a new, all zero, 4x4 matrix.

func NewM4I 

func NewM4I() *M4

NewM4I creates a new 4x4 identity matrix. 

[ 1 0 0 0 ]    [ Xx Xy Xz Xw ]
[ 0 1 0 0 ] => [ Yx Yy Yz Yw ]
[ 0 0 1 0 ]    [ Zx Zy Zz Zw ]
[ 0 0 0 1 ]    [ Wx Wy Wz Ww ]

func (*M4) Add 

func (m *M4) Add(a, b *M4) *M4

Add (+) adds matrices a and b storing the results in m. Same behaviour as M3.Add()

func (*M4) Aeq 

func (m *M4) Aeq(a *M4) bool

Aeq (~=) almost equals returns true if all the elements in matrix m have essentially the same value as the corresponding elements in matrix a. Same as M3.Aeq().

func (*M4) Eq 

func (m *M4) Eq(a *M4) bool

Eq (==) returns true if all the elements in matrix m have the same value as the corresponding elements in matrix a.

func (*M4) Mult 

func (m *M4) Mult(l, r *M4) *M4

Mult updates matrix m to be the multiplication of input matrices l, r. 

[ lXx lXy lXz lXw ] [ rXx rXy rXz rXw ]    [ mXx mXy mXz mXw ]
[ lYx lYy lYz lYw ]x[ rYx rYy rYz rYw ] => [ mYx mYy mYz mYw ]
[ lZx lZy lZz lZw ] [ rZx rZy rZz rZw ]    [ mZx mZy mZz mZw ]
[ lWx lWy lWz lWw ] [ rWx rWy rWz rWw ]    [ mWx mWy mWz mWw ]

Same behaviour as M3.Mult()

func (*M4) OrthographicProjection added in v0.20.0 

func (m *M4) OrthographicProjection(left, right, bottom, top, near, far float64) *M4

OrthographicProjection for Vulkan sets matrix m with values needed to transform a view vector to clip space. Objects apparent size will not be affected by distance the camera. Input arguments are: 

width, height: clipping planes.
near, far    : depth clipping planes.

Assumes frustrum is centered on the z-axis.

based on https://github.com/vkngwrapper/math/blob/main/mat4x4.go: SetOrthographic FUTURE: consider using SetOrthographic2D for 2D render pass.

func (*M4) PerspectiveInverse added in v0.20.0 

func (m *M4) PerspectiveInverse(fov, aspect, near, far float64) *M4

PerspectiveInverse sets matrix m to be a new inverse perspective projection matrix. Can be used when going from screen x,y coordinates to 3D coordinates. as in the case when creating a picking ray from a mouse location. 

fov        field of view in degrees indicating how much of the
           scene is visible.
aspect     The ratio of height to width of the model.
near, far  The depth clipping planes. The depth values are
           negative if the plane is to be behind the viewer

func (*M4) PerspectiveProjection added in v0.20.0 

func (m *M4) PerspectiveProjection(fov, aspect, near, far float64) *M4

PerspectiveProjection for Vulkan sets matrix m with values needed to convert a view vector to clip space. Objects further away from the viewer will appear smaller. The input arguments are: 

fov        field of view in degrees indicating how much of the
           scene is visible.
aspect     The ratio of height to width.
near, far  The depth clipping planes.

Assumes frustrum is centered on the z-axis.

func (*M4) Scale 

func (m *M4) Scale(s float64) *M4

Scale (*) each element of matrix m by the given scalar. The updated matrix m is returned.

func (*M4) ScaleMS 

func (m *M4) ScaleMS(x, y, z float64) *M4

ScaleMS updates m to be the multiplication of m and a scale matrix created from x, y, z. The updated matrix m is returned. 

[ mXx mXy mXz mXw ]   [ x 0 0 0 ]    [ mXx' mXy' mXz' mXw ]
[ mYx mYy mYz mYw ] x [ 0 y 0 0 ] => [ mYx' mYy' mYz' mYw ]
[ mZx mZy mZz mZw ]   [ 0 0 z 0 ]    [ mZx' mZy' mZz' mZw ]
[ mWx mWy mWz mWw ]   [ 0 0 0 1 ]    [ mWx' mWy' mWz' mWw ]

Be sure to pick the correct scale (SM or MS) when doing transforms.

func (*M4) ScaleSM 

func (m *M4) ScaleSM(x, y, z float64) *M4

ScaleSM updates m to be the multiplication of a scale matrix created from x, y, z and itself. Same behaviours as M3.ScaleSM. 

[ x 0 0 0 ]   [ mXx mXy mXz mXw ]    [ mXx' mXy' mXz' mXw' ]
[ 0 y 0 0 ] x [ mYx mYy mYz mYw ] => [ mYx' mYy' mYz' mYw' ]
[ 0 0 z 0 ]   [ mZx mZy mZz mZw ]    [ mZx' mZy' mZz' mZw' ]
[ 0 0 0 1 ]   [ mWx mWy mWz mWw ]    [ mWx  mWy  mWz  mWw  ]

func (*M4) Set 

func (m *M4) Set(a *M4) *M4

Set (=) assigns all the elements values from matrix a to the corresponding element values in matrix m. The source matrix a is unchanged. The updated matrix m is returned.

func (*M4) SetQ 

func (m *M4) SetQ(q *Q) *M4

SetQ converts a quaternion rotation representation to a matrix rotation representation. SetQ updates matrix m to be the rotation matrix representing the rotation described by unit-quaternion q. 

                   [ mXx mXy mXz 0 ]
[ qx qy qz qw ] => [ mYx mYy mYz 0 ]
                   [ mZx mZy mZz 0 ]
                   [  0   0   0  1 ]

The parameter q is unchanged. The updated matrix m is returned.

func (*M4) TranslateMT 

func (m *M4) TranslateMT(x, y, z float64) *M4

TranslateMT updates m to be the multiplication of itself and a translation matrix created from x, y, z. The updated matrix m is returned. 

[ mXx mXy mXz mXw ]   [ 1 0 0 0 ]    [ mXx' mXy' mXz' mXw ]
[ mYx mYy mYz mYw ] x [ 0 1 0 0 ] => [ mYx' mYy' mYz' mYw ]
[ mZx mZy mZz mZw ]   [ 0 0 1 0 ]    [ mZx' mZy' mZz' mZw ]
[ mWx mWy mWz mWw ]   [ x y z 1 ]    [ mWx' mWy' mWz' mWw ]

Be sure to pick the correct translate (TM or MT) when doing transforms.

func (*M4) TranslateTM 

func (m *M4) TranslateTM(x, y, z float64) *M4

TranslateTM updates m to be the multiplication of a translation matrix T created from x, y, z, and itself. The updated matrix m is returned. 

[ 1 0 0 0 ]   [ mXx mXy mXz mXw ]    [ mXx  mXy  mXz  mXw  ]
[ 0 1 0 0 ] x [ mYx mYy mYz mYw ] => [ mYx  mYy  mYz  mYw  ]
[ 0 0 1 0 ]   [ mZx mZy mZz mZw ]    [ mZx  mZy  mZz  mZw  ]
[ x y z 1 ]   [ mWx mWy mWz mWw ]    [ mWx' mWy' mWz' mWw' ]

Be sure to pick the correct translate (TM or MT) when doing transforms.

func (*M4) Transpose 

func (m *M4) Transpose(a *M4) *M4

Transpose updates m to be the reflection of matrix a over its diagonal. 

[ Xx Xy Xz Xw ]    [ Xx Yx Zx Wx ]
[ Yx Yy Yz Yw ] => [ Xy Yy Zy Wy ]
[ Zx Zy Zz Zw ]    [ Xz Yz Zz Wz ]
[ Wx Wy Wz Ww ]    [ Xw Yw Zw Ww ]

Same behaviour as M3.Transpose()

type Number added in v0.20.0 

type Number interface {
	~int | ~int8 | ~int16 | ~uint16 | ~int32 | ~uint32 | ~int64 | ~uint64 | ~float32 | ~float64
}

Number accepts the basic number types and other types that are redefines of the basic number types.

type Q 

type Q struct {
	X float64 // X component of direction vector.
	Y float64 // Y component of direction vector.
	Z float64 // Z component of direction vector.
	W float64 // Angle of rotation.
}

Q is a unit length quaternion representing an angle of rotation. Q is used to track/manipulate 3D object rotations. Quaternions behave nicely for mathematical operations other than they are not commutative.

func NewQ 

func NewQ() *Q

NewQ creates a new, all zero, quaternion.

func NewQI 

func NewQI() *Q

NewQI creates a new identity quaternion.

func (*Q) Aa 

func (q *Q) Aa() (ax, ay, az, angle float64)

Aa gets the rotation of quaternion q as an axis and angle. The axis (x, y, z) and the angle in radians is returned. The return elements will be zero if the length of the quaternion is 0. See: 

http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q57

func (*Q) Add 

func (q *Q) Add(r, s *Q) *Q

Add (+) quaternions r and s returning the result in quaternion q.

func (*Q) Aeq 

func (q *Q) Aeq(r *Q) bool

Aeq (~=) almost-equals returns true if all the elements in quaternion q have essentially the same value as the corresponding elements in quaternion r. Used where a direct comparison is unlikely to return true due to floats.

func (*Q) Ang 

func (q *Q) Ang(r *Q) float64

Ang returns the angle in radians between quaternions q and r. For the formula to calculate angles between quaternions see:

func (*Q) Div 

func (q *Q) Div(s float64) *Q

Div (/= inverse-scale) divides each element in q by the given scalar value. Scale values of zero are logged as an error and q is not scaled. The updated q is returned.

func (*Q) Dot 

func (q *Q) Dot(r *Q) float64

Dot returns the dot product of the quaternions q and r. Quaternion q may be used as the input parameter. For example (Dot=), the length squared, is 

q.Dot(q)

func (*Q) Eq 

func (q *Q) Eq(r *Q) bool

Eq (==) returns true if each element in the quaternion q has the same value as the corresponding element in quaterion r.

func (*Q) GetS 

func (q *Q) GetS() (x, y, z, w float64)

GetS returns the component parts of a quaternion.

func (*Q) Inv 

func (q *Q) Inv(r *Q) *Q

Inv updates q to be inverse of quaternion r. The updated q is returned. The inverse of a quaternion is the same as the conjugate, as long as the quaternion is unit-length.

func (*Q) Len 

func (q *Q) Len() float64

Len returns the length of the quaternion q.

func (*Q) Mult 

func (q *Q) Mult(r, s *Q) *Q

Mult (*) multiplies quaternions r and s returning the result in q. This applies the rotation of s to r giving q, leaving r and s unchanged. It is safe to use the calling quaternion q as one or both of the parameters. For example (*=) is 

q.Mult(q, s)

The updated calling quaternion q is returned.

func (*Q) MultQV 

func (q *Q) MultQV(r *Q, v *V3) *Q

MultQV multiplies quaternion r and vector v and returns the result in quaternion q. The upated quaternion q is returned.

func (*Q) Neg 

func (q *Q) Neg() *Q

Neg (-) returns the negative of quaternion q where each element is negated. The updated q is returned.

func (*Q) Nlerp 

func (q *Q) Nlerp(r, s *Q, ratio float64) *Q

Nlerp updates q to be the normalized linear interpolation between quaternions r and s where ratio is expected to be between 0 and 1. The input quaternions r and s are not changed. See:

The updated calling quaternion q is returned.

func (*Q) Scale 

func (q *Q) Scale(s float64) *Q

Scale (*=) quaternion q by s returning the result in quaternion q.

func (*Q) Set 

func (q *Q) Set(r *Q) *Q

Set (=) assigns all the elements values from quaternion r to the corresponding element values in quaternion q. The updated quaternion q is returned.

func (*Q) SetAa 

func (q *Q) SetAa(ax, ay, az, angle float64) *Q

SetAa set axis-angle, updates q to have the rotation of the given axis (ax, ay, az) and angle (in radians). See: 

http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q56

The updated quaternion q is returned. The quaternion q is set to 0,0,0,1 if the axis length is 0.

Ensure SetAa returns quaternions consistent with SetM3. Convention 5 from "Consistent Representations of and Conversions Between 3D Rotations": 

"The rotation angle ω is limited to the interval [0, π].
 For angles in the range ]π, 2π[, the sign of the unit axis vector nˆ
 must be reversed, and ω replaced by 2π − ω. For angles outside the range
 [0, 2π[, the angle must first be reduced to the interval [0, 2π[ by
 adding or subtracting the appropriate integer multiple of 2π."

func (*Q) SetM3 added in v0.9.0 

func (q *Q) SetM3(m *M3) *Q

SetM3 updates quaternion q to be the rotation of matrix m. See 

http://www.flipcode.com/documents/matrfaq.html#Q55
http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/
https://d3cw3dd2w32x2b.cloudfront.net/wp-content/uploads/2015/01/matrix-to-quat.pdf

The updated q is returned.

SetM3 outputs quaternions that are consistent with SetAa.

func (*Q) SetS 

func (q *Q) SetS(x, y, z, w float64) *Q

SetS (=) explicitly sets each of the quaternion values to the given values. The updated quaternion q is returned.

func (*Q) SetT 

func (q *Q) SetT(t *T) *Q

SetT updates quaternion q to have the rotation in transform t. The updated quaternion q is returned.

func (*Q) Sub 

func (q *Q) Sub(r, s *Q) *Q

Sub (-) subtracts quaternion s from r returning the difference in quaternion q.

func (*Q) Unit 

func (q *Q) Unit() *Q

Unit normalizes quaternion q to have length 1. The normalized (unit length) q is returned. Quaternion q is not updated if the length of quaternion q is zero.

type T 

type T struct {
	Loc *V3 // Location (translation, origin).
	Rot *Q  // Rotation (direction, orientation).
}

T is a 3D transform for rotation and translation. It excludes scaling and shear information. T is used as a simplification and optimization instead of keeping all transform information in a 4x4 matrix.

T supports linear algebra operations that are similar to those supported by V3, V4, M3, M4, and Q. The main ones are: 

Multiply two transforms together to produce a composite transform.
Apply a transform or inverse transform to a vector.

func NewT 

func NewT() *T

NewT creates and returns a transform at the origin with no rotation.

func (*T) Aeq 

func (t *T) Aeq(a *T) bool

Aeq (~=) almost-equals returns true if all the elements in transform t have essentially the same value as the corresponding elements in transform a. Used where a direct comparison is unlikely to return true due to floats.

func (*T) App 

func (t *T) App(v *V3) *V3

App applies its transform to vector v. The updated vector v is returned.

func (*T) AppR 

func (t *T) AppR(x, y, z float64) (vx, vy, vz float64)

AppR applies just the transform rotation to input vector (x,y,z) returning the rotated vector (vx,vy,vz)

func (*T) AppS 

func (t *T) AppS(x, y, z float64) (vx, vy, vz float64)

AppS applies transform t, rotation then translation, to input scalar vector (x,y,z) returning the transformed scalar vector (vx,vy,vz).

func (*T) Eq 

func (t *T) Eq(a *T) bool

Eq (==) returns true of all elements of transform t have the same value as the corresponding element of transform a.

func (*T) Integrate 

func (t *T) Integrate(a *T, linv, angv *V3, dt float64) *T

Integrate updates transform t to be the linear integration of transform a with the given linear velocity linv, and angular velocity angv over the given amount of time dt. Transforms t and a must be distinct. The input vectors linv, angv are not changed. The updated transform t is returned.

Based on bullet physics: btTransformUtil::integrateTransform.

func (*T) Inv 

func (t *T) Inv(v *V3) *V3

Inv updates vector v to be the inverse transform t applied to vector a. The updated vector v is returned.

func (*T) InvS 

func (t *T) InvS(x, y, z float64) (vx, vy, vz float64)

InvS applies the inverse transform t, inverse translation, then inverse rotation, to input vector (x,y,z) returning the transformed vector (vx,vy,vz).

func (*T) Mult 

func (t *T) Mult(a, b *T) *T

Mult (*) updates the transform t to be the product of the transforms a and b. Transform t may be used as one or both of the input transforms. The updated transform t is returned.

func (*T) Set 

func (t *T) Set(a *T) *T

Set (=, copy, clone) assigns all the elements values from transform a to the corresponding element values in transform t. The updated transform t is returned.

func (*T) SetAa 

func (t *T) SetAa(ax, ay, az, ang float64) *T

SetAa updates transform t to have the rotation specified by the given axis and angle in radians. The updated transform t is returned.

func (*T) SetI 

func (t *T) SetI() *T

SetI updates transform t to be the identity transform. The updated transform t is returned.

func (*T) SetLoc 

func (t *T) SetLoc(lx, ly, lz float64) *T

SetLoc updates transform t to have the location speccified by lx, ly, lz. The updated transform t is returned.

func (*T) SetRot 

func (t *T) SetRot(x, y, z, w float64) *T

SetRot updates transform t to have the rotation specified by x, y, z, w. The updated transform t is returned.

func (*T) SetVQ 

func (t *T) SetVQ(loc *V3, rot *Q) *T

SetVQ (=) sets the transform t based on the given quaternion rotation and translation location. The updated transform t is returned.

type V3 

type V3 struct {
	X float64 // increments as X moves to the right.
	Y float64 // increments as Y moves up from bottom left.
	Z float64 // increments as Z moves out of the screen (right handed view space).
}

V3 is a 3 element vector. This can also be used as a point.

func NewV3 

func NewV3() *V3

NewV3 creates a new, all zero, 3D vector.

func NewV3S 

func NewV3S(x, y, z float64) *V3

NewV3S creates a new 3D vector using the given scalars.

func (*V3) Abs 

func (v *V3) Abs() *V3

Abs updates vector v to have the absolute value of the elements of vector a. The updated vector v is returned.

func (*V3) Add 

func (v *V3) Add(a, b *V3) *V3

Add (+) adds vectors a and b storing the results of the addition in v. Vector v may be used as one or both of the parameters. For example (+=) is 

v.Add(v, b)

The updated vector v is returned.

func (*V3) Aeq 

func (v *V3) Aeq(a *V3) bool

Aeq (~=) almost-equals returns true if all the elements in vector v have essentially the same value as the corresponding elements in vector a. Used where a direct comparison is unlikely to return true due to floats.

func (*V3) AeqZ 

func (v *V3) AeqZ() bool

AeqZ (~=) almost equals zero returns true if the square length of the vector is close enough to zero that it makes no difference.

func (*V3) Ang 

func (v *V3) Ang(a *V3) float64

Ang returns the angle in radians between vector v and input vector a. Ang returns 0 if the magnitude of the two vectors is 0.

func (*V3) AppT 

func (v *V3) AppT(t *T, a *V3) *V3

AppT updates vector v to be the transform t applied to vector a. Vector a is unchanged. The updated vector v is returned.

func (*V3) Cross 

func (v *V3) Cross(a, b *V3) *V3

Cross updates v to be the cross product of vectors a and b. A cross product vector is a vector that is perpendicular to both input vectors. This is only meaningful in 3 (or 7) dimensions. Input vectors a and b are unchanged. Vector v may be used as either input parameter.The updated vector v is returned.

func (*V3) Dist 

func (v *V3) Dist(a *V3) float64

Dist returns the distance between vector end-points v and a Both vectors (points) v and a are unchanged.

func (*V3) DistSqr 

func (v *V3) DistSqr(a *V3) float64

DistSqr returns the distance squared between vector end-points v and a. Both vectors (points) v and a are unchanged.

func (*V3) Div 

func (v *V3) Div(s float64) *V3

Div (/= inverse-scale) divides each element in v by the given scalar value. The updated vector v is returned. Vector v is not changed if scalar s is zero.

func (*V3) Dot 

func (v *V3) Dot(a *V3) float64

Dot vector v with input vector a. Both vectors v and a are unchanged. Wikipedia states: 

"This operation can be defined either algebraically or geometrically.
 Algebraically, it is the sum of the products of the corresponding
 entries of the two sequences of numbers. Geometrically, it is the
 product of the magnitudes of the two vectors and the cosine of
 the angle between them."

func (*V3) Eq 

func (v *V3) Eq(a *V3) bool

Eq (==) returns true if each element in the vector v has the same value as the corresponding element in vector a.

func (*V3) Forward added in v0.20.0 

func (v *V3) Forward(q *Q) *V3

Forward sets v to to be the result of applying the quaternion rotation to the Z direction, equivalent to MultSQ(0, 0, 1, q)

func (*V3) ForwardInverted added in v0.20.0 

func (v *V3) ForwardInverted(q *Q) *V3

ForwardInverted sets v to to be the result of applying the opposite quaternion rotation to the Z direction.

func (*V3) GetS 

func (v *V3) GetS() (x, y, z float64)

GetS returns the float64 values of the vector.

func (*V3) Len 

func (v *V3) Len() float64

Len returns the length of vector v. Vector length is the square root of the dot product. The calling vector v is unchanged.

func (*V3) LenSqr 

func (v *V3) LenSqr() float64

LenSqr returns the length of vector v squared. The calling vector v is unchanged.

func (*V3) Lerp 

func (v *V3) Lerp(a, b *V3, fraction float64) *V3

Lerp updates vector v to be a fraction of the distance (linear interpolation) between the input vectors a and b. The input ratio is not verified, but is expected to be between 0 and 1. Vector v may be used as one of the parameters.

func (*V3) Max 

func (v *V3) Max(a, b *V3) *V3

Max updates the vector v elements to be the maxiumum of the corresponding elements from either vectors a or b. The updated vector v is returned.

func (*V3) Min 

func (v *V3) Min(a, b *V3) *V3

Min updates the vector v elements to be the minimum of the corresponding elements from either vectors a or b. The updated vector v is returned.

func (*V3) Mult 

func (v *V3) Mult(a, b *V3) *V3

Mult (*) multiplies the elements of vectors a and b storing the result in v. Vector v may be used as one or both of the parameters. For example (*=) is For example (*=) is 

v.Mult(v, b)

The updated vector v is returned.

func (*V3) MultMv 

func (v *V3) MultMv(m *M3, cv *V3) *V3

MultMv updates vector v to be the multiplication of matrix m and column vector cv. Vector v may be used as the input vector cv. The updated vector v is returned. 

[ Xx Xy Xz ]   [ vx ]   [ vx' ]
[ Yx Yy Yz ] x [ vy ] = [ vx' ]
[ Zx Zy Zz ]   [ vz ]   [ vz' ]

func (*V3) MultQ 

func (v *V3) MultQ(a *V3, q *Q) *V3

MultQ (*) multiplies a vector by quaternion, effectively applying the rotation of quaternion q to vector a and storing the result in v. The input vector a, and quaternion q are unchanged.

func (*V3) MultvM 

func (v *V3) MultvM(rv *V3, m *M3) *V3

MultvM updates vector v to be the multiplication of row vector rv and matrix m. Vector v may be used as the input vector rv. The updated vector v is returned. 

               [ Xx Xy Xz ]
[ vx vy vz ] x [ Yx Yy Yz ] = [ vx' vy' vz' ]
               [ Zx Zy Zz ]

func (*V3) Neg 

func (v *V3) Neg(a *V3) *V3

Neg (-) sets vector v to be the negative values of vector a. Vector v may be used as the input parameter. The updated vector v is returned.

func (*V3) Nlerp 

func (v *V3) Nlerp(a, b *V3, ratio float64) *V3

Nlerp updates vector v to be a normalized vector that is the linerar interpolation between a and b. See: 

http://keithmaggio.wordpress.com/2011/02/15/math-magician-lerp-slerp-and-nlerp/
http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/

The calling vector v may be used as either or both of the input parameters.

func (*V3) Plane 

func (v *V3) Plane(p, q *V3)

Plane generates 2 vectors perpendicular to normal vector v. The perpendicular vectors and are returned as values of vectors p and q.

Based on bullet physics: btVector3::btPlaneSpace1

func (*V3) Right added in v0.20.0 

func (v *V3) Right(q *Q) *V3

Right sets v to to be the result of applying the quaternion rotation to the X direction, equivalent to MultSQ(1, 0, 0, q)

func (*V3) RightInverted added in v0.20.0 

func (v *V3) RightInverted(q *Q) *V3

RightInverted sets v to to be the result of applying the opposite quaternion rotation to the X direction.

func (*V3) Scale 

func (v *V3) Scale(a *V3, s float64) *V3

Scale (*=) updates the elements in vector v by multiplying the corresponding elements in vector a by the given scalar value. Vector v may be used as one or both of the vector parameters. The updated vector v is returned.

func (*V3) Set 

func (v *V3) Set(a *V3) *V3

Set (=, copy, clone) sets the elements of vector v to have the same values as the elements of vector a. The updated vector v is returned.

func (*V3) SetS 

func (v *V3) SetS(x, y, z float64) *V3

SetS (=) sets the vector elements to the given values. The updated vector v is returned.

func (*V3) Sub 

func (v *V3) Sub(a, b *V3) *V3

Sub (-) subtracts vectors b from a storing the results of the subtraction in v. Vector v may be used as one or both of the parameters. For example (-=) is 

v.Sub(v, b)

The updated vector v is returned.

func (*V3) Swap 

func (v *V3) Swap(a *V3) *V3

Swap exchanges the element values of vectors v and a. The updated vector v is returned. Vector a is also updated.

func (*V3) Unit 

func (v *V3) Unit() *V3

Unit updates vector v such that its length is 1. Calling vector v is unchanged if its length is zero. The updated vector v is returned.

func (*V3) Up added in v0.20.0 

func (v *V3) Up(q *Q) *V3

Up sets v to to be the result of applying the quaternion rotation to the Y direction, equivalent to MultSQ(0, 1, 0, q)

func (*V3) UpInverted added in v0.20.0 

func (v *V3) UpInverted(q *Q) *V3

UpInverted sets v to to be the result of applying the opposite quaternion rotation to the Y direction.

type V4 

type V4 struct {
	X float64 // increments as X moves to the right.
	Y float64 // increments as Y moves up from bottom left.
	Z float64 // increments as Z moves out of the screen (right handed view space).
	W float64 // fourth dimension makes for nice 3D matrix math.
}

V4 is a 4 element vector. It can be used for points and directions where, as a point it would have W:1, and as a direction it would have W:0.

func NewV4 

func NewV4() *V4

NewV4 creates a new, all zero, 4D vector.

func NewV4S 

func NewV4S(x, y, z, w float64) *V4

NewV4S creates a new 3D vector using the given scalars.

func (*V4) Abs 

func (v *V4) Abs() *V4

Abs updates vector v to have the absolute value of the elements of vector a. Same behaviour as V3.Abs().

func (*V4) Add 

func (v *V4) Add(a, b *V4) *V4

Add (+) adds vectors a and b storing the results of the addition in v. Same behaviour as V3.Add().

func (*V4) AeqZ 

func (v *V4) AeqZ() bool

AeqZ (~=) almost equals zero returns true if the square length of the vector is close enough to zero that it makes no difference.

func (*V4) Div 

func (v *V4) Div(s float64) *V4

Div (/= inverse-scale) divides each element in v by the given scalar value. Same behaviour as V3.Div().

func (*V4) Dot 

func (v *V4) Dot(a *V4) float64

Dot vector v with input vector a. Same behaviour as V3.Dot()

func (*V4) Eq 

func (v *V4) Eq(a *V4) bool

Eq (==) returns true if each element in the vector v has the same value as the corresponding element in vector a.

func (*V4) GetS 

func (v *V4) GetS() (x, y, z, w float64)

GetS returns the float64 values of the vector.

func (*V4) Len 

func (v *V4) Len() float64

Len returns the length of vector v. Same behaviour as V3.Len()

func (*V4) LenSqr 

func (v *V4) LenSqr() float64

LenSqr returns the length of vector v squared. Same behaviour as V3.LenSqr()

func (*V4) Lerp 

func (v *V4) Lerp(a, b *V4, ratio float64) *V4

Lerp updates vector v to be a fraction of the distance (linear interpolation) between the input vectors a and b. Same behaviour as V3.Lerp()

func (*V4) Max 

func (v *V4) Max(a, b *V4) *V4

Max updates the vector v elements to be the maximum of the corresponding elements from either vectors a or b. Same behaviour as V3.Max().

func (*V4) Min 

func (v *V4) Min(a, b *V4) *V4

Min updates the vector v elements to be the minimum of the corresponding elements from either vectors a or b. Same behaviour as V3.Min().

func (*V4) Mult 

func (v *V4) Mult(a, b *V4) *V4

Mult (*) multiplies the elements of vectors a and b storing the result in v. Same behaviour as V3.Mult().

func (*V4) MultMv 

func (v *V4) MultMv(m *M4, cv *V4) *V4

MultMv updates vector v to be the multiplication of matrix m and column vector cv. Same behaviour as V3.MultMv(). 

[ Xx Xy Xz Xw ]   [ vx ]   [ vx' ]
[ Yx Yy Yz Yw ] x [ vy ] = [ vy' ]
[ Zx Zy Zz Zw ]   [ vz ]   [ vz' ]
[ Wx Wy Wz Ww ]   [ vw ]   [ vw' ]

func (*V4) MultvM 

func (v *V4) MultvM(rv *V4, m *M4) *V4

MultvM updates vector v to be the multiplication of row vector rv and matrix m. Same behaviour as V3.MultvM(). 

                  [ Xx Xy Xz Xw ]
[ vx vy vz vw ] x [ Yx Yy Yz Yw ] = [ vx' vy' vz' vw']
                  [ Zx Zy Zz Zw ]
                  [ Wx Wy Wz Ww ]

func (*V4) Neg 

func (v *V4) Neg(a *V4) *V4

Neg (-) sets vector v to be the negative values of vector a. Same behaviour as V3.Neg().

func (*V4) Nlerp 

func (v *V4) Nlerp(a, b *V4, ratio float64) *V4

Nlerp updates vector v to be a normalized vector that is the linerar interpolation between a and b. Same behaviour as V3.Lerp()

func (*V4) Scale 

func (v *V4) Scale(a *V4, s float64) *V4

Scale (*=) updates the elements in vector v by multiplying the corresponding elements in vector a by the given scalar value. Same behaviour as V3.Scale().

func (*V4) Set 

func (v *V4) Set(a *V4) *V4

Set (=, copy, clone) sets the elements of vector v to have the same values as the elements of vector a. The updated vector v is returned.

func (*V4) SetS 

func (v *V4) SetS(x, y, z, w float64) *V4

SetS (=) sets the vector elements to the given values. The updated vector v is returned.

func (*V4) Sub 

func (v *V4) Sub(a, b *V4) *V4

Sub (-) subtracts vectors b from a storing the results of the subtraction in v. Same behaviour as V3.Sub().

func (*V4) Swap 

func (v *V4) Swap(a *V4) *V4

Swap exchanges the element values of vectors v and a. Same behaviour as V3.Swap().

func (*V4) Unit 

func (v *V4) Unit() *V4

Unit updates vector v such that its length is 1. Same behaviour as V3.Unit()

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.