FastMath

About FastMath

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

License

record TVector3

DescriptionHierarchyFieldsMethodsProperties

Unit

Neslib.FastMath

Declaration

type TVector3 = record

Description

A 3-dimensional vector. Can be used for a variety of purposes:

  • To represent points or vectors in 3D space, using the X, Y and Z fields.

  • To represent colors (using the R, G and B fields, which are just aliases for X, Y and Z)

  • To represent texture coordinates (S, T and P, again just aliases for X, Y and Z).

  • To group 3 arbitrary values together in an array (C[0]..C[2], also just aliases for X, Y and Z)

Note: when possible, use TVector4 instead of TVector3, since TVector4 has better hardware support. Operations on TVector4 types are usually faster than operations on TVector3 types.

TVector3 is compatible with TPoint3D in the Delphi RTL. You can typecast between these two types or implicitly convert from one to the other through assignment (eg. MyVector3 := MyPoint3D).

Overview

Fields

X: Single
Y: Single
Z: Single
R: Single
G: Single
B: Single
S: Single
T: Single
P: Single
C: array [0..2] of Single

Methods

procedure Init; overload; inline;
procedure Init(const A: Single); overload; inline;
procedure Init(const A1, A2, A3: Single); overload; inline;
procedure Init(const A1: TVector2; const A2: Single); overload; inline;
procedure Init(const A1: Single; const A2: TVector2); overload; inline;
class operator Implicit(const A: TPoint3D): TVector3; inline;
class operator Implicit(const A: TVector3): TPoint3D; inline;
class operator Equal(const A, B: TVector3): Boolean; inline;
class operator NotEqual(const A, B: TVector3): Boolean; inline;
class operator Negative(const A: TVector3): TVector3;
class operator Add(const A: TVector3; const B: Single): TVector3;
class operator Add(const A: Single; const B: TVector3): TVector3;
class operator Add(const A, B: TVector3): TVector3;
class operator Subtract(const A: TVector3; const B: Single): TVector3;
class operator Subtract(const A: Single; const B: TVector3): TVector3;
class operator Subtract(const A, B: TVector3): TVector3;
class operator Multiply(const A: TVector3; const B: Single): TVector3;
class operator Multiply(const A: Single; const B: TVector3): TVector3;
class operator Multiply(const A, B: TVector3): TVector3;
class operator Divide(const A: TVector3; const B: Single): TVector3; inline;
class operator Divide(const A: Single; const B: TVector3): TVector3;
class operator Divide(const A, B: TVector3): TVector3;
function Equals(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean; inline;
function Distance(const AOther: TVector3): Single;
function DistanceSquared(const AOther: TVector3): Single;
function Dot(const AOther: TVector3): Single; inline;
function Cross(const AOther: TVector3): TVector3;
procedure Offset(const ADeltaX, ADeltaY, ADeltaZ: Single); overload; inline;
procedure Offset(const ADelta: TVector3); overload; inline;
function Normalize: TVector3; inline;
procedure SetNormalized; inline;
function NormalizeFast: TVector3;
procedure SetNormalizedFast;
function FaceForward(const I, NRef: TVector3): TVector3; inline;
function Reflect(const N: TVector3): TVector3;
function Refract(const N: TVector3; const Eta: Single): TVector3;
function Limit(const AMaxLength: Single): TVector3; inline;
procedure SetLimit(const AMaxLength: Single); inline;
function LimitSquared(const AMaxLengthSquared: Single): TVector3;
procedure SetLimitSquared(const AMaxLengthSquared: Single);
function Clamp(const AMinLength, AMaxLength: Single): TVector3;
procedure SetClamped(const AMinLength, AMaxLength: Single);
function Lerp(const ATarget: TVector3; const AAlpha: Single): TVector3; inline;
procedure SetLerp(const ATarget: TVector3; const AAlpha: Single); inline;
function IsNormalized: Boolean; overload; inline;
function IsNormalized(const AErrorMargin: Single): Boolean; overload;
function IsZero: Boolean; overload; inline;
function IsZero(const AErrorMargin: Single): Boolean; overload;
function HasSameDirection(const AOther: TVector3): Boolean; inline;
function HasOppositeDirection(const AOther: TVector3): Boolean; inline;
function IsParallel(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;
function IsCollinear(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;
function IsCollinearOpposite(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;
function IsPerpendicular(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;

Properties

property Components[constAIndex:Integer]: Single read GetComponent write SetComponent;
property Length: Single read GetLength write SetLength;
property LengthSquared: Single read GetLengthSquared write SetLengthSquared;

Description

Fields

X: Single

X, Y and Z components of the vector. Aliases for C[0], C[1] and C[2].

Y: Single

X, Y and Z components of the vector. Aliases for C[0], C[1] and C[2].

Z: Single

X, Y and Z components of the vector. Aliases for C[0], C[1] and C[2].

R: Single

Red, Green and Blue components of the vector. Aliases for C[0], C[1] and C[2].

G: Single

Red, Green and Blue components of the vector. Aliases for C[0], C[1] and C[2].

B: Single

Red, Green and Blue components of the vector. Aliases for C[0], C[1] and C[2].

S: Single

S, T and P components of the vector. Aliases for C[0], C[1] and C[2].

T: Single

S, T and P components of the vector. Aliases for C[0], C[1] and C[2].

P: Single

S, T and P components of the vector. Aliases for C[0], C[1] and C[2].

C: array [0..2] of Single

The three components of the vector.

Methods

procedure Init; overload; inline;

Sets the three elements (X, Y and Z) to 0.

procedure Init(const A: Single); overload; inline;

Sets the three elements (X, Y and Z) to A.

Parameters
A
the value to set the three elements to.
procedure Init(const A1, A2, A3: Single); overload; inline;

Sets the three elements (X, Y and Z) to A1, A2 and A3 respectively.

Parameters
A1
the value to set the first element to.
A2
the value to set the second element to.
A3
the value to set the third element to.
procedure Init(const A1: TVector2; const A2: Single); overload; inline;

Sets the first two elements from a 2D vector, and the third element from a scalar.

Parameters
A1
the vector to use for the first two elements.
A2
the value to set the third element to.
procedure Init(const A1: Single; const A2: TVector2); overload; inline;

Sets the first element from a scaler, and the last two elements from a 2D vector.

Parameters
A1
the value to set the first element to.
A2
the vector to use for the last two elements.
class operator Implicit(const A: TPoint3D): TVector3; inline;

Implicitly converts a TPoint3D to a TVector3.

class operator Implicit(const A: TVector3): TPoint3D; inline;

Implicitly converts a TVector3 to a TPoint3D.

class operator Equal(const A, B: TVector3): Boolean; inline;

Checks two vectors for equality.

Returns

True if the two vectors match each other exactly.

class operator NotEqual(const A, B: TVector3): Boolean; inline;

Checks two vectors for inequality.

Returns

True if the two vectors are not equal.

class operator Negative(const A: TVector3): TVector3;

Negates a vector.

Returns

The negative value of a vector (eg. (-A.X, -A.Y, -A.Z))

class operator Add(const A: TVector3; const B: Single): TVector3;

Adds a scalar value to a vector.

Returns

(A.X + B, A.Y + B, A.Z + B)

class operator Add(const A: Single; const B: TVector3): TVector3;

Adds a vector to a scalar value.

Returns

(A + B.X, A + B.Y, A + B.Z)

class operator Add(const A, B: TVector3): TVector3;

Adds two vectors.

Returns

(A.X + B.X, A.Y + B.Y, A.Z + B.Z)

class operator Subtract(const A: TVector3; const B: Single): TVector3;

Subtracts a scalar value from a vector.

Returns

(A.X - B, A.Y - B, A.Z - B)

class operator Subtract(const A: Single; const B: TVector3): TVector3;

Subtracts a vector from a scalar value.

Returns

(A - B.X, A - B.Y, A - B.Z)

class operator Subtract(const A, B: TVector3): TVector3;

Subtracts two vectors.

Returns

(A.X - B.X, A.Y - B.Y, A.Z - B.Z)

class operator Multiply(const A: TVector3; const B: Single): TVector3;

Multiplies a vector with a scalar value.

Returns

(A.X * B, A.Y * B, A.Z * B)

class operator Multiply(const A: Single; const B: TVector3): TVector3;

Multiplies a scalar value with a vector.

Returns

(A * B.X, A * B.Y, A * B.Z)

class operator Multiply(const A, B: TVector3): TVector3;

Multiplies two vectors component-wise. To calculate a dot or cross product instead, use the Dot or Cross function.

Returns

(A.X * B.X, A.Y * B.Y, A.Z * B.Z)

class operator Divide(const A: TVector3; const B: Single): TVector3; inline;

Divides a vector by a scalar value.

Returns

(A.X / B, A.Y / B, A.Z / B)

class operator Divide(const A: Single; const B: TVector3): TVector3;

Divides a scalar value by a vector.

Returns

(A / B.X, A / B.Y, A / B.Z)

class operator Divide(const A, B: TVector3): TVector3;

Divides two vectors component-wise.

Returns

(A.X / B.X, A.Y / B.Y, A.Z / B.Z)

function Equals(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean; inline;

Whether this vector equals another vector, within a certain tolerance.

Parameters
AOther
the other vector.
ATolerance
(optional) tolerance. If not specified, a small tolerance is used.
Returns

True if both vectors are equal (within the given tolerance).

function Distance(const AOther: TVector3): Single;

Calculates the distance between this vector and another vector.

Note: If you only want to compare distances, you should use DistanceSquared instead, which is faster.

Parameters
AOther
the other vector.
Returns

The distance between this vector and AOther.

function DistanceSquared(const AOther: TVector3): Single;

Calculates the squared distance between this vector and another vector.

Parameters
AOther
the other vector.
Returns

The squared distance between this vector and AOther.

function Dot(const AOther: TVector3): Single; inline;

Calculates the dot product between this vector and another vector.

Parameters
AOther
the other vector.
Returns

The dot product between this vector and AOther.

function Cross(const AOther: TVector3): TVector3;

Calculates the cross product between this vector and another vector.

Parameters
AOther
the other vector.
Returns

The cross product between this vector and AOther.

procedure Offset(const ADeltaX, ADeltaY, ADeltaZ: Single); overload; inline;

Offsets this vector in a certain direction.

Parameters
ADeltaX
the delta X direction.
ADeltaY
the delta Y direction.
ADeltaZ
the delta Z direction.
procedure Offset(const ADelta: TVector3); overload; inline;

Offsets this vector in a certain direction.

Note: this is equivalent to adding two vectors together.

Parameters
ADelta
the delta.
function Normalize: TVector3; inline;

Calculates a normalized version of this vector.

Note: for a faster, less accurate version, use NormalizeFast.

Note: Does not change this vector. To update this vector itself, use SetNormalized.

Returns

The normalized version of of this vector. That is, a vector in the same direction as A, but with a length of 1.

procedure SetNormalized; inline;

Normalizes this vector. This is, keep the current direction, but set the length to 1.

Note: The SIMD optimized versions of this method use an approximation, resulting in a very small error.

Note: If you do not want to change this vector, but get a normalized version instead, then use Normalize.

function NormalizeFast: TVector3;

Calculates a normalized version of this vector.

Note: this is an SIMD optimized version that uses an approximation, resulting in a small error. For an accurate version, use Normalize.

Note: Does not change this vector. To update this vector itself, use SetNormalizedFast.

Returns

The normalized version of of this vector. That is, a vector in the same direction as A, but with a length of 1.

procedure SetNormalizedFast;

Normalizes this vector. This is, keep the current direction, but set the length to 1.

Note: this is an SIMD optimized version that uses an approximation, resulting in a small error. For an accurate version, use SetNormalized.

Note: If you do not want to change this vector, but get a normalized version instead, then use NormalizeFast.

function FaceForward(const I, NRef: TVector3): TVector3; inline;

Calculates a vector pointing in the same direction as this vector.

Parameters
I
the incident vector.
NRef
the reference vector.
Returns

A vector that points away from the surface as defined by its normal. If NRef.Dot(I) < 0 then it returns this vector, otherwise it returns the negative of this vector.

function Reflect(const N: TVector3): TVector3;

Calculates the reflection direction for this (incident) vector.

Parameters
N
the normal vector. Should be normalized in order to achieve the desired result.
Returns

The reflection direction calculated as Self - 2 * N.Dot(Self) * N.

function Refract(const N: TVector3; const Eta: Single): TVector3;

Calculates the refraction direction for this (incident) vector.

Note: This vector should be normalized in order to achieve the desired result.

Parameters
N
the normal vector. Should be normalized in order to achieve the desired result.
Eta
the ratio of indices of refraction.
Returns

The refraction vector.

function Limit(const AMaxLength: Single): TVector3; inline;

Creates a vector with the same direction as this vector, but with the length limited, based on the desired maximum length.

Note: Does not change this vector. To update this vector itself, use SetLimit.

Parameters
AMaxLength
The desired maximum length of the vector.
Returns

A length-limited version of this vector.

procedure SetLimit(const AMaxLength: Single); inline;

Limits the length of this vector, based on the desired maximum length.

Note: If you do not want to change this vector, but get a length-limited version instead, then use Limit.

Parameters
AMaxLength
The desired maximum length of this vector.
function LimitSquared(const AMaxLengthSquared: Single): TVector3;

Creates a vector with the same direction as this vector, but with the length limited, based on the desired squared maximum length.

Note: Does not change this vector. To update this vector itself, use SetLimitSquared.

Parameters
AMaxLengthSquared
The desired squared maximum length of the vector.
Returns

A length-limited version of this vector.

procedure SetLimitSquared(const AMaxLengthSquared: Single);

Limits the length of this vector, based on the desired squared maximum length.

Note: If you do not want to change this vector, but get a length-limited version instead, then use LimitSquared.

Parameters
AMaxLengthSquared
The desired squared maximum length of this vector.
function Clamp(const AMinLength, AMaxLength: Single): TVector3;

Creates a vector with the same direction as this vector, but with the length clamped between a minimim and maximum length.

Note: Does not change this vector. To update this vector itself, use SetClamped.

Parameters
AMinLength
The minimum length of the vector.
AMaxLength
The maximum length of the vector.
Returns

A length-clamped version of this vector.

procedure SetClamped(const AMinLength, AMaxLength: Single);

Clamps the length of this vector between a minimim and maximum length.

Note: If you do not want to change this vector, but get a length-clamped version instead, then use Clamp.

Parameters
AMinLength
The minimum length of this vector.
AMaxLength
The maximum length of this vector.
function Lerp(const ATarget: TVector3; const AAlpha: Single): TVector3; inline;

Linearly interpolates between this vector and a target vector.

Note: Does not change this vector. To update this vector itself, use SetLerp.

Parameters
ATarget
the target vector.
AAlpha
the interpolation coefficient (between 0.0 and 1.0).
Returns

The interpolation result vector.

procedure SetLerp(const ATarget: TVector3; const AAlpha: Single); inline;

Linearly interpolates between this vector and a target vector and stores the result in this vector.

Note: If you do not want to change this vector, but get an interpolated version instead, then use Lerp.

Parameters
ATarget
the target vector.
AAlpha
the interpolation coefficient (between 0.0 and 1.0).
function IsNormalized: Boolean; overload; inline;

Whether the vector is normalized (within a small margin of error).

Returns

True if the length of the vector is (very close to) 1.0

function IsNormalized(const AErrorMargin: Single): Boolean; overload;

Whether the vector is normalized within a given margin of error.

Parameters
AErrorMargin
the allowed margin of error.
Returns

True if the squared length of the vector is 1.0 within the margin of error.

function IsZero: Boolean; overload; inline;

Whether this is a zero vector.

Returns

True if X, Y and Z are exactly 0.0

function IsZero(const AErrorMargin: Single): Boolean; overload;

Whether this is a zero vector within a given margin of error.

Parameters
AErrorMargin
the allowed margin of error.
Returns

True if the squared length is smaller then the margin of error.

function HasSameDirection(const AOther: TVector3): Boolean; inline;

Whether this vector has a similar direction compared to another vector.

Parameters
AOther
the other vector.
Returns

True if the normalized dot product is greater than 0.

function HasOppositeDirection(const AOther: TVector3): Boolean; inline;

Whether this vector has an opposite direction compared to another vector.

Parameters
AOther
the other vector.
Returns

True if the normalized dot product is less than 0.

function IsParallel(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;

Whether this vector runs parallel to another vector (either in the same or the opposite direction).

Parameters
AOther
the other vector.
ATolerance
(optional) tolerance. If not specified, a small tolerance is used.
Returns

True if this vector runs parallel to AOther (within the given tolerance)

function IsCollinear(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;

Whether this vector is collinear with another vector. Two vectors are collinear if they run parallel to each other and point in the same direction.

Parameters
AOther
the other vector.
ATolerance
(optional) tolerance. If not specified, a small tolerance is used.
Returns

True if this vector is collinear to AOther (within the given tolerance)

function IsCollinearOpposite(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;

Whether this vector is opposite collinear with another vector. Two vectors are opposite collinear if they run parallel to each other and point in opposite directions.

Parameters
AOther
the other vector.
ATolerance
(optional) tolerance. If not specified, a small tolerance is used.
Returns

True if this vector is opposite collinear to AOther (within the given tolerance)

function IsPerpendicular(const AOther: TVector3; const ATolerance: Single = SINGLE_TOLERANCE): Boolean;

Whether this vector is perpendicular to another vector.

Parameters
AOther
the other vector.
ATolerance
(optional) tolerance. If not specified, a small tolerance is used.
Returns

True if this vector is perpendicular to AOther. That is, if the dot product is 0 (within the given tolerance)

Properties

property Components[constAIndex:Integer]: Single read GetComponent write SetComponent;

Returns the components of the vector. This is identical to accessing the C-field, but this property can be used as a default array property.

Parameters
AIndex
index of the component to return (0-2). Range is checked with an assertion.
property Length: Single read GetLength write SetLength;

The euclidean length of this vector.

Note: If you only want to compare lengths of vectors, you should use LengthSquared instead, which is faster.

Note: You can also set the length of the vector. In that case, it will keep the current direction.

property LengthSquared: Single read GetLengthSquared write SetLengthSquared;

The squared length of the vector.

Note: This property is faster than Length because it avoids calculating a square root. It is useful for comparing lengths instead of calculating actual lengths.

Note: You can also set the squared length of the vector. In that case, it will keep the current direction.

Generated by PasDocEx, based on PasDoc 0.14.0.