Vector3

package
v0.0.0-...-2b43b64 Latest Latest
Warning

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

 Go to latest Published: Jan 29, 2025 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package Vector3 provides a 3D vector using floating-point coordinates.

Index

Constants

This section is empty.

Variables

View Source 
var (
	Zero  = XYZ{0, 0, 0}                         // Zero vector, a vector with all components set to 0.
	One   = XYZ{1, 1, 1}                         // One vector, a vector with all components set to 1.
	Inf   = XYZ{Float.Inf, Float.Inf, Float.Inf} // Inf vector, a vector with all components set to positive infinity.
	Left  = XYZ{-1, 0, 0}                        // Left unit vector. Represents the local direction of left, and the global direction of west.
	Right = XYZ{1, 0, 0}                         // Right unit vector. Represents the local direction of right, and the global direction of east.
	Up    = XYZ{0, 1, 0}                         // Up unit vector.
	Down  = XYZ{0, -1, 0}                        // Down unit vector.

	// Forward unit vector. Represents the local direction of forward, and the global direction
	// of north. Keep in mind that the forward direction for lights, cameras, etc is different
	// from 3D assets like characters, which face towards the camera by convention. Use [ModelFront]
	// and similar constants when working in 3D asset space.
	Forward = XYZ{0, 0, -1}

	Back = XYZ{0, 0, 1} // Back unit vector. Represents the local direction of back, and the global direction of south.

	ModelLeft   = XYZ{1, 0, 0}  // Unit vector pointing towards the left side of imported 3D assets.
	ModelRight  = XYZ{-1, 0, 0} // Unit vector pointing towards the right side of imported 3D assets.
	ModelTop    = XYZ{0, 1, 0}  // Unit vector pointing towards the top side of imported 3D assets.
	ModelBottom = XYZ{0, -1, 0} // Unit vector pointing towards the bottom side of imported 3D assets.
	ModelFront  = XYZ{0, 0, 1}  // Unit vector pointing towards the front side of imported 3D assets.
	ModelRear   = XYZ{0, 0, -1} // Unit vector pointing towards the rear side of imported 3D assets.
)

Functions

func AngleBetween 

func AngleBetween(a, b XYZ) Angle.Radians

AngleBetween returns the unsigned minimum angle to the given vector, in radians.

func AsArray 

func AsArray(vec XYZ) [3]Float.X

func Distance 

func Distance(v, to XYZ) Float.X

Distance returns the distance between this vector and to.

func DistanceSquared 

func DistanceSquared(v, to XYZ) Float.X

DistanceSquared returns the squared distance between this vector and to.

This method runs faster than [Vector3.DistanceTo], so prefer it if you need to compare vectors or need the squared distance for some formula.

func Dot 

func Dot(a, b XYZ) Float.X

Dot returns the dot product of this vector and with. This can be used to compare the angle between two vectors. For example, this can be used to determine whether an enemy is facing the player.

The dot product will be 0 for a straight angle (90 degrees), greater than 0 for angles narrower than 90 degrees and lower than 0 for angles wider than 90 degrees.

When using unit (normalized) vectors, the result will always be between -1.0 (180 degree angle) when the vectors are facing opposite directions, and 1.0 (0 degree angle) when the vectors are aligned.

Note: a.Dot(b) is equivalent to b.Dot(a).

func Index 

func Index[I Int.Any](v XYZ, i I) Float.X

func IsApproximatelyEqual 

func IsApproximatelyEqual(a, b XYZ) bool

IsApproximatelyEqual returns true if this vector and other are approximately equal, by running [Float.IsApproximatelyEqual] on each component.

func IsApproximatelyZero 

func IsApproximatelyZero(v XYZ) bool

IsApproximatelyZero returns true if this vector is approximately equal to zero, by running [Float.IsApproximatelyZero] on each component.

func IsFinite 

func IsFinite(v XYZ) bool

IsFinite returns true if this vector's values are finite, by running [Float.IsFinite] on each component.

func IsNormalized 

func IsNormalized(v XYZ) bool

IsNormalized Returns true if the vector is normalized, i.e. its length is approximately equal to 1.

func Length 

func Length(v XYZ) Float.X

Length the length (magnitude) of this vector.

func LengthSquared 

func LengthSquared(v XYZ) Float.X

LengthSquared returns the squared length (squared magnitude) of this vector.

This method runs faster than length, so prefer it if you need to compare vectors or need the squared distance for some formula.

func Less 

func Less(a, b XYZ) bool

Less compares two Vector3 vectors by first checking if the X value of the left vector is less than the X value of the right vector. If the X values are exactly equal, then it repeats this check with the Y and Z values of the two vectors. This operator is useful for sorting vectors.

Note: Vectors with NaN elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included.

func OctahedronEncode 

func OctahedronEncode(v XYZ) Vector2.XY

OctahedronEncode returns the octahedral-encoded (oct32) form of this [Vector3] as a [Vector2]. Since a [Vector2] occupies 1/3 less memory compared to [Vector3], this form of compression can be used to pass greater amounts of normalized [Vector3]s without increasing storage or memory requirements. See also [Vector3.OctahedronDecode].

Note: OctahedronEncode can only be used for normalized vectors. OctahedronEncode does not check whether this [Vector3] is normalized, and will return a value that does not decompress to the original value if the [Vector3] is not normalized.

Note: Octahedral compression is lossy, although visual differences are rarely perceptible in real world scenarios.

func SignedAngle 

func SignedAngle(v, to XYZ, axis XYZ) Angle.Radians

SignedAngle returns the signed angle to the given vector, in radians. The sign of the angle is positive in a counter-clockwise direction and negative in a clockwise direction when viewed from the side specified by the axis.

Types

type Axis 

type Axis int
const (
	X Axis = iota // Enumerated value for the X axis. Returned by [MaxAxis] and [MinAxis].
	Y             // Enumerated value for the Y axis. Returned by [MaxAxis] and [MinAxis].
	Z             // Enumerated value for the Z axis. Returned by [MaxAxis] and [MinAxis].
)

func MaxAxis 

func MaxAxis(v XYZ) Axis

MaxAxis returns the axis of the vector's highest value. See Axis constants. If all components are equal, this method returns X.

func MinAxis 

func MinAxis(v XYZ) Axis

MinAxis returns the axis of the vector's lowest value. See Axis constants. If all components are equal, this method returns Z.

type XYZ 

type XYZ = struct {
	X Float.X // The vector's X component.
	Y Float.X // The vector's Y component.
	Z Float.X // The vector's Z component.
}

XYZ is a 3-element structure that can be used to represent 3D coordinates or any other triplet of numeric values.

It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike float which is always 64-bit. If double precision is needed, compile with the Go build tag 'precision_double'.

See [Vector3i.XYZ] for its integer counterpart.

func Abs 

func Abs(v XYZ) XYZ

Abs returns a new vector with all components in absolute values (i.e. positive).

func Add 

func Add(a, b XYZ) XYZ

func AddX 

func AddX[X Float.Any | Int.Any](a XYZ, b X) XYZ

func BezierDerivative 

func BezierDerivative[X Float.Any](v, control1, control2, end XYZ, t X) XYZ

BezierDerivative returns the derivative at the given t on the Bézier curve defined by this vector and the given control_1, control_2, and end points.

func BezierInterpolate 

func BezierInterpolate[X Float.Any](v, control1, control2, end XYZ, t X) XYZ

BezierInterpolate returns the point at the given t on the Bézier curve defined by this vector and the given control_1, control_2, and end points.

func Bounce 

func Bounce(v, n XYZ) XYZ

Bounce returns the vector "bounced off" from a plane defined by the given normal.

func Ceil 

func Ceil(v XYZ) XYZ

Ceil returns a new vector with all components rounded up (towards positive infinity).

func Clamp 

func Clamp(v, min, max XYZ) XYZ

Clamp returns a new vector with all components clamped between the components of min and max, by running [Float.Clamp] on each component.

func Clampf 

func Clampf[X Float.Any](v XYZ, min, max X) XYZ

Clampf returns a new vector with all components clamped between the components of min and max, by running [Float.Clamp] on each component.

func Cross 

func Cross(v, with XYZ) XYZ

Cross returns the cross product of this vector and with.

func CubicInterpolate 

func CubicInterpolate[X Float.Any](v, b, preA, postB XYZ, weight X) XYZ

CubicInterpolate performs a cubic interpolation between this vector and b using pre_a and post_b as handles and returns the result at position weight. weight is on the range of 0.0 to 1.0, representing the amount of interpolation.

func CubicInterpolateInTime 

func CubicInterpolateInTime[X Float.Any](v, b, preA, postB XYZ, weight, b_t, pre_a_t, post_b_t X) XYZ

CubicInterpolateInTime performs a cubic interpolation between this vector and b using pre_a and post_b as handles and returns the result at position weight. weight is on the range of 0.0 to 1.0, representing the amount of interpolation.

It can perform smoother interpolation than [Vector3.CubicInterpolate] by the time values.

func Direction 

func Direction(v, to XYZ) XYZ

Direction returns the normalized vector pointing from this vector to to. This is equivalent to using Normalized(b - a).

func Div 

func Div(a, b XYZ) XYZ

func DivX 

func DivX[X Float.Any | Int.Any](a XYZ, b X) XYZ

func Floor 

func Floor(v XYZ) XYZ

Floor returns a new vector with all components rounded down (towards negative infinity).

func Inverse 

func Inverse(v XYZ) XYZ

Inverse returns the inverse of the vector. This is the same as 

XYZ{1/v.X,1/v.Y,1/v.Z}.

func LengthLimited 

func LengthLimited[X Float.Any](v XYZ, length X) XYZ

LimitLength returns the vector with a maximum length by limiting its length to length.

func Lerp 

func Lerp[X Float.Any](v, to XYZ, weight X) XYZ

Lerp returns the result of the linear interpolation between this vector and to by amount weight. weight is on the range of 0.0 to 1.0, representing the amount of interpolation.

func Max 

func Max(a, b XYZ) XYZ

Max returns the component-wise minimum of this and with, equivalent to 

Vector3.New(max(x, with.x), max(y, with.y), max(z, with.z))

func Maxf 

func Maxf[X Float.Any](v XYZ, with X) XYZ

Maxf returns the component-wise maximum of this and with, equivalent to 

Vector3.New(max(x, with), max(y, with), max(z, with)).

func Min 

func Min(a, b XYZ) XYZ

Min returns the component-wise minimum of this and with, equivalent to 

Vector3.New(min(x, with.x), min(y, with.y), min(z, with.z))

func Minf 

func Minf[X Float.Any](v XYZ, with X) XYZ

Minf returns the component-wise minimum of this and with, equivalent to 

Vector3.New(min(x, with), min(y, with), min(z, with), min(w, with)).

func Move 

func Move[X Float.Any](a, b XYZ, delta X) XYZ

Move returns a new vector moved toward to by the fixed delta amount. Will not go past the final value.

func Mul 

func Mul(a, b XYZ) XYZ

func MulX 

func MulX[X Float.Any | Int.Any](a XYZ, b X) XYZ

func Neg 

func Neg(v XYZ) XYZ

func New 

func New[X Int.Any | Float.Any](x, y, z X) XYZ

New returns a XYZ with the given components.

func Normalized 

func Normalized(v XYZ) XYZ

Normalized returns the result of scaling the vector to unit length. Equivalent to v / v.Length(). See also IsNormalized.

Note: This function may return incorrect values if the input vector length is near zero.

func OctahedronDecode 

func OctahedronDecode(uv Vector2.XY) XYZ

OctahedronDecode returns the XYZ from an octahedral-compressed form created using OctahedronEncode (stored as a [Vector2.XY]).

func Posmod 

func Posmod(v, mod XYZ) XYZ

Posmod returns a vector composed of the Fposmod of this vector's components and mod.

func Posmodf 

func Posmodf[X Float.Any](v XYZ, mod X) XYZ

Posmodf returns a vector composed of the Fposmod of this vector's components and mod.

func Project 

func Project(v, b XYZ) XYZ

Project returns the result of projecting the vector onto the given vector b.

func Reflect 

func Reflect(v, n XYZ) XYZ

Reflect returns the result of reflecting the vector from a plane defined by the given normal n.

func Rotated 

func Rotated(v, axis XYZ, angle Angle.Radians) XYZ

Rotated returns the result of rotating this vector around a given axis by angle (in radians). The axis must be a normalized vector.

func Round 

func Round(v XYZ) XYZ

Round returns a new vector with all components rounded to the nearest integer, with halfway cases rounded away from zero.

func Sign 

func Sign(vec XYZ) XYZ

Sign returns a new vector with each component set to 1.0 if it's positive, -1.0 if it's negative, and 0.0 if it's zero. The result is identical to calling [Signf] on each component.

func Slerp 

func Slerp[X Float.Any](v, to XYZ, weight X) XYZ

Slerp returns the result of spherical linear interpolation between this vector and to, by amount weight. weight is on the range of 0.0 to 1.0, representing the amount of interpolation.

This method also handles interpolating the lengths if the input vectors have different lengths. For the special case of one or both input vectors having zero length, this method behaves like lerp.

func Slide 

func Slide(v, n XYZ) XYZ

Slide returns a new vector slid along a plane defined by the given normal.

func Snapped 

func Snapped(v, step XYZ) XYZ

Snapped returns a new vector with each component snapped to the nearest multiple of the corresponding component in step. This can also be used to round the components to an arbitrary number of decimals.

func Snappedf 

func Snappedf[X Float.Any](v XYZ, step X) XYZ

Snappedf returns a new vector with each component snapped to the nearest multiple of step. This can also be used to round the components to an arbitrary number of decimals.

func Sub 

func Sub(a, b XYZ) XYZ

func SubX 

func SubX[X Float.Any | Int.Any](a XYZ, b X) XYZ

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.