Detailed Description

A high-performance three-dimensional vector implementation optimized for Saturn hardware.

Vector3D extends Vector2D to provide comprehensive 3D vector operations using fixed-point arithmetic. It inherits all 2D functionality while adding Z-axis operations and 3D-specific algorithms optimized for performance-critical graphics and physics calculations.

Key features:

Memory-efficient representation (three Fxp values)
Comprehensive set of 3D vector operations (cross product, normalization, etc.)
Multiple precision levels for performance-critical operations
Hardware-optimized calculations for Saturn platform
Inheritance from Vector2D for seamless 2D/3D interoperability

Common applications:

3D positions and translations
Surface normals and orientation vectors
Physics simulations (velocities, forces, torques)
Camera and view transformations
Lighting calculations

The implementation follows a right-handed coordinate system where:

Positive X points right
Positive Y points up
Positive Z points toward the viewer (out of the screen)

Performance considerations:

Most operations are constexpr and can be evaluated at compile time
Precision template parameters allow trading accuracy for speed
Fixed-point arithmetic avoids expensive floating-point operations
Specialized implementations for common operations (unit vectors, etc.)

Note: When working with operations that require normalization (like calculating normals), be aware of the performance implications and consider using the appropriate precision level based on your requirements.

See also: Vector2D For 2D vector operations; Fxp For details on the fixed-point implementation; Precision For available precision levels in calculations

#include <vector3d.hpp>

Inheritance diagram for SRL::Math::Types::Vector3D:

Public Member Functions
constexpr	Vector3D ()
	Default constructor, initializes all coordinates to 0.

constexpr	Vector3D (const Fxp &fxp)
	Constructor to initialize all coordinates with the same value.

constexpr	Vector3D (const Fxp &valueX, const Fxp &valueY, const Fxp &valueZ)
	Constructor to initialize coordinates with specific values.

constexpr	Vector3D (const Vector2D &vec2d, const Fxp &valueZ)
	Constructor to initialize from a Vector2D and a Z coordinate.

constexpr	Vector3D (const Vector3D &vec)
	Copy constructor.

constexpr Vector3D	Abs () const
	Calculate the absolute values of each coordinate.

constexpr Fxp	Cross (const Vector2D &vec) const
	Calculate the cross product (z-component) of this vector and another Vector2D.

constexpr Vector3D	Cross (const Vector3D &vec) const
	Calculate the cross product of this object and another Vec3 object.

template<Precision P = Precision::Default>
constexpr Fxp	DistanceTo (const Vector2D &other) const
	Calculate the Euclidean distance from this vector to another vector.

template<Precision P = Precision::Default>
constexpr Fxp	DistanceTo (const Vector3D &other) const
	Calculate the Euclidean distance from this vector to another vector.

constexpr Fxp	Dot (const Vector2D &vec) const
	Calculate the dot product of this vector with another vector.

constexpr Fxp	Dot (const Vector3D &vec) const
	Calculate the dot product of this object and another Vec3 object.

template<Precision P = Precision::Default>
constexpr Fxp	Length () const
	Calculate the length of the vector.

constexpr Fxp	LengthSquared () const
	Calculate the squared length of the vector.

template<Precision P = Precision::Default>
constexpr Vector3D	Normalize () const
	Normalize the vector.

constexpr bool	operator!= (const Vector2D &vec) const
	Check if two Vec3 objects are not equal.

constexpr bool	operator!= (const Vector3D &vec) const
	Check if two Vec3 objects are not equal.

constexpr Vector3D	operator* (const Fxp &scalar) const
	Scalar multiplication operator.

template<typename T> requires std::is_integral_v<T>
constexpr Vector3D	operator* (const T &scalar) const
	Scalar multiplication operator for integral types.

constexpr Vector3D &	operator*= (const Fxp &scalar)
	Compound multiplication assignment operator.

template<typename T> requires std::is_integral_v<T>
constexpr Vector3D &	operator*= (const T &scalar)
	Compound multiplication assignment operator for integral types.

constexpr Vector3D	operator+ (const Fxp &scalar) const
	Binary addition operator for adding an Fxp to a Vector3D.

constexpr Vector3D	operator+ (const Vector2D &vec) const
	Binary addition operator for adding a Vector2D to a Vector3D.

constexpr Vector3D	operator+ (const Vector3D &vec) const
	Binary addition operator.

constexpr Vector2D &	operator+= (const Vector2D &vec)
	Compound addition assignment operator.

constexpr Vector3D	operator+= (const Vector3D &vec)
	Compound addition assignment operator.

constexpr Vector2D	operator- (const Vector2D &vec) const
	Vector subtraction operator.

constexpr Vector3D	operator- () const
	Unary negation operator.

constexpr Vector3D	operator- (const Vector3D &vec) const
	Binary subtraction operator.

constexpr Vector2D &	operator-= (const Vector2D &vec)
	Compound subtraction assignment operator.

constexpr Vector3D	operator-= (const Vector3D &vec)
	Compound subtraction assignment operator.

constexpr Vector3D	operator/ (const Fxp &scalar) const
	Scalar division operator.

template<typename T> requires std::is_integral_v<T>
constexpr Vector3D	operator/ (const T &scalar) const
	Scalar division operator for integral types.

constexpr Vector3D &	operator/= (const Fxp &scalar)
	Compound division assignment operator.

template<typename T> requires std::is_integral_v<T>
constexpr Vector3D &	operator/= (const T &scalar)
	Compound division assignment operator for integral types.

constexpr bool	operator< (const Vector2D &vec) const
	Less than operator.

constexpr bool	operator< (const Vector3D &vec) const
	Less than operator.

constexpr Vector3D	operator<< (const size_t &shiftAmount)
	Bitwise left shift operator.

constexpr Vector3D &	operator<<= (const size_t &shiftAmount)
	Bitwise left shift assignment operator.

constexpr bool	operator<= (const Vector2D &vec) const
	Less than or equal operator.

constexpr bool	operator<= (const Vector3D &vec) const
	Less than or equal operator.

constexpr Vector3D &	operator= (const Vector3D &vec)
	Assignment operator.

constexpr bool	operator== (const Vector2D &vec) const
	Check if two Vec3 objects are not equal.

constexpr bool	operator== (const Vector3D &vec) const
	Check if two Vec3 objects are equal.

constexpr bool	operator> (const Vector2D &vec) const
	Greater than operator.

constexpr bool	operator> (const Vector3D &vec) const
	Greater than operator.

constexpr bool	operator>= (const Vector2D &vec) const
	Greater than or equal operator.

constexpr bool	operator>= (const Vector3D &vec) const
	Greater than or equal operator.

constexpr Vector3D	operator>> (const size_t &shiftAmount)
	Bitwise right shift operator.

constexpr Vector3D &	operator>>= (const size_t &shiftAmount)
	Bitwise right shift assignment operator.

template<SortOrder O = SortOrder::Ascending>
constexpr Vector2D	Sort () const
	Sort coordinates in specified order.

template<SortOrder O = SortOrder::Ascending>
constexpr Vector3D	Sort ()
	Sort coordinates in ascending order.

Static Public Member Functions
template<Precision P = Precision::Default>
static Vector3D	CalcNormal (const Vector3D &vertexA, const Vector3D &vertexB, const Vector3D &vertexC)
	Calculate normal vector for a triangle.

static void	DotAccumulate (const Vector2D &first, const Vector2D &second)
	Helper function to perform assembly-level dot product calculation and accumulation.

static void	DotAccumulate (const Vector3D &first, const Vector3D &second)
	Helper function to perform assembly-level dot product calculation and accumulation.

static consteval Vector2D	Down ()
	Get a vector pointing down (0,-1).

static consteval Vector2D	Left ()
	Get a vector pointing left (-1,0).

template<typename... Pairs>
static constexpr Fxp	MultiDotAccumulate (const Pairs &... pairs)
	Calculate and accumulate the dot products of multiple 3D vector pairs.

static consteval Vector3D	One ()
	Get a vector with all components set to one (1,1,1).

static consteval Vector2D	Right ()
	Get a vector pointing right (1,0). Same as UnitX(), provided for semantic clarity.

static consteval Vector3D	UnitX ()
	Get a unit vector pointing along the X axis (1,0,0).

static consteval Vector3D	UnitY ()
	Get a unit vector pointing along the Y axis (0,1,0).

static consteval Vector3D	UnitZ ()
	Get a unit vector pointing along the Z axis (0,0,1).

static consteval Vector2D	Up ()
	Get a vector pointing up (0,1). Same as UnitY(), provided for semantic clarity.

static consteval Vector3D	Zero ()
	Get a zero vector (0,0,0).

Public Attributes
Fxp	X

Fxp	Y

Fxp	Z

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes