<p align="center"> <img src="https://github.com/robertoduarte/SaturnMathPP/blob/main/documentation/resources/smpp_sqrt_pi_logo.svg" > </p>

SaturnMath++

<p align="center"> <img src="https://img.shields.io/badge/C%2B%2B-23-blue" alt="C++23"> <img src="https://img.shields.io/badge/Platform-Sega%20Saturn-yellow" alt="Platform"> </p>

SaturnMath++ is a high-performance mathematical library specifically engineered for Sega Saturn game development. It provides a comprehensive suite of fixed-point arithmetic operations, vector/matrix transformations, and geometric calculations optimized for the Saturn's SH-2 processors.

Overview

Developed with the Saturn's unique hardware architecture in mind, SaturnMath++ addresses the platform's key constraints while maximizing performance:

• Fixed-Point Precision: Replaces costly floating-point operations with optimized 16.16 fixed-point arithmetic
• Hardware-Aware Design: Takes advantage of the SH-2's 32-bit operations and instruction set
• Performance-First Philosophy: Offers multiple precision levels to balance accuracy and speed
• Modern C++ Features: Leverages C++23 capabilities for compile-time optimizations
• Zero Overhead: No dynamic memory allocation, minimal branching, and cache-friendly data structures

Whether you're developing a 3D racing game, a 2D sprite-based platformer, or a complex simulation, SaturnMath++ provides the mathematical foundation you need without sacrificing precious CPU cycles.

Architecture

SaturnMath++ is organized into two main namespaces:

SaturnMath::Types

Contains all fundamental mathematical types and structures:

• Vector arithmetic (Vector2D, Vector3D)
• Matrix operations (Mat33, Matrix43)
• Geometric primitives (AABB, Sphere, Plane, Frustum)
• Fixed-point numbers (Fxp)
• Angle representation optimized for Saturn hardware

SaturnMath

Provides mathematical operations and utilities:

• Trigonometric functions
• Interpolation methods
• Integer-specific optimizations
• Template-based utility functions for common operations (Min, Max, Abs, Clamp)

Features

Core Components

• Fixed-Point Arithmetic: High-performance Fxp class with precise fixed-point operations

  • Power function for integer exponents
  • Value clamping between bounds
  • Comprehensive arithmetic operations
  • MinValue and MaxValue constants for range boundaries
  • Modulo operations for both Fxp and integer types
  • Flexible value conversion:

    // Compile-time conversion (preferred)
    constexpr Fxp a = 3.14159;   // Exact conversion at compile-time (float)
    constexpr Fxp b = 42;         // Integer conversion at compile-time (int16_t)
    
    // Runtime conversion with safety checks
    int32_t someInt = GetRuntimeValue();
    Fxp c = Fxp::Convert(someInt);   // Range checking (converts to int16_t first)
    
    // Runtime floating-point conversion (with performance warning)
    float someFloat = GetRuntimeFloat();
    Fxp d = Fxp::Convert(someFloat); // Warning: heavy operation on Saturn hardware
    
    // Disable performance warnings for specific sections if needed
    #define DISABLE_PERFORMANCE_WARNINGS
    #include "saturn_math.hpp"
    // Now conversion warnings are suppressed in this compilation unit
    
    // Converting back to other types
    int16_t i = a.As<int16_t>();     // To integer
    float f = a.As<float>();         // To float (with performance warning)
    

  • Advanced Usage: For experts who understand the 16.16 fixed-point format, direct raw value manipulation is available:

    // Create from raw 16.16 value (for advanced users only)
    Fxp raw = Fxp::BuildRaw(0x00010000);  // 1.0 in 16.16 format
    
    // Hardware-optimized asynchronous division
    Fxp dividend = 10;
    Fxp divisor = 3;
    Fxp::AsyncDivSet(dividend, divisor);
    Fxp quotient = Fxp::AsyncDivGetResult();    // Get division result
    Fxp remainder = Fxp::AsyncDivGetRemainder(); // Get remainder
    

  • Comparison Operators: Comprehensive comparison support with important runtime limitations:

    // These work at both compile-time and runtime
    Fxp a(5);
    Fxp b(3);
    
    if (a > b) { /* This works fine */ }
    if (a == 5) { /* This works fine */ }
    if (a > 40.0) { /* This works fine - Fxp on LEFT side */ }
    
    // These ONLY work at compile-time due to C++ language limitations
    constexpr Fxp c(7);
    constexpr bool test1 = (5 < c);  // Works in constexpr context
    constexpr bool test2 = (9.5 > c);  // Works in constexpr context
    
    // This will NOT work at runtime:
    int value = GetRuntimeValue();
    Fxp d(10);
    // if (value < d) { /* COMPILE ERROR - non-Fxp on LEFT side */ }
    // if (40.0 < d) { /* COMPILE ERROR - non-Fxp on LEFT side */ }
    
    // KEY POINT: The order matters!
    // This works: fxpValue > 40.0  (Fxp on left side)
    // This fails: 40.0 < fxpValue  (Fxp on right side)
    
    // Solutions:
    // 1. Use the Convert method for runtime values:
    int runtimeValue = GetRuntimeValue();
    Fxp convertedValue = Fxp::Convert(runtimeValue);
    if (convertedValue < d) { /* This works fine */ }
    
    // 2. Flip the comparison if possible:
    if (d > runtimeValue) { /* This works fine */ }
    if (d > 40.0) { /* This works fine */ }
    

  • Conversion Best Practices:

    // For COMPILE-TIME literals, use direct constructor:
    constexpr Fxp a(5);      // Integer literal - efficient
    constexpr Fxp b(3.14);   // Float literal - efficient at compile-time
    
    // For RUNTIME integer values, use the Convert method:
    int runtimeInt = GetValue();
    Fxp c = Fxp::Convert(runtimeInt); // Convert method - safer with range checking
    
    // For RUNTIME float values, avoid if possible (CPU intensive):
    float runtimeFloat = GetValue();
    // Fxp d(runtimeFloat);          // ERROR: Won't compile, constructor only works with compile-time floats
    Fxp d = Fxp::Convert(runtimeFloat); // Works but VERY expensive on Saturn hardware
    
    // For comparisons with runtime values, prefer flipping the comparison:
    // AVOID: if (Fxp(runtimeInt) < a) - can have limitations
    // BETTER: if (a > runtimeInt) - works consistently
    

  • Angle Handling: Type-safe Angle class for angular calculations
  • Raw value construction and access
  • Scalar multiplication and division
  • Automatic wrap-around handling
  • Comprehensive comparison operators with wrap-around considerations
  • Performance warnings for angle conversions (can be disabled)

  // Angle operations with comparison
  Angle angle1 = Angle::FromDegrees(45);
  Angle angle2 = Angle::FromDegrees(90);
  
  if (angle1 < angle2) {
      // This works, but be cautious near wrap-around boundaries
  }
  
  // Disable performance warnings when needed
  #define DISABLE_PERFORMANCE_WARNINGS
  #include "saturn_math.hpp"
  // Now conversion warnings are suppressed
  

• Euler Angles: Type-safe representation of 3D rotations

  • Intrinsic Tait-Bryan angles (pitch-yaw-roll)
  • X-Y-Z rotation order
  • Zero-initialization support

Vectors and Matrices

• 2D Vectors: Vector2D class with optimized operations
  • Unit vectors (UnitX, UnitY)
  • Directional vectors (Left, Right, Up, Down)
  • Multiple precision levels for normalization and length calculations
• 3D Vectors: Vector3D class extending Vector2D functionality
  • Unit vectors (UnitX, UnitY, UnitZ)
  • Optimized cross/dot products
  • Template-based precision control for geometric operations
  • Optimized operators for integral types
• Matrix Operations: Efficient Matrix33 and Matrix43 implementations
  • Common transformations (scale, rotate, translate)
  • Optimized multiplication with detailed documentation
  • Identity/zero matrix constants
  • Row-based layout with clear geometric meaning
  • Orthonormal basis in right-handed coordinate system
  • Billboard matrix creation
  • Look-at matrix for camera positioning
  • Transform decomposition into scale/rotation/translation
  • EulerAngles support for rotations
• Matrix Stack: Fixed-size stack for transform hierarchies
  • No dynamic allocation
  • Depth checking
  • Direct transformation methods

Geometric Primitives

• AABB: Axis-aligned bounding box with comprehensive intersection tests
  • Fast min/max calculations
  • Volume and surface area computation
  • Merging and expansion operations
• Sphere: Perfect sphere with exact collision detection
  • Point containment tests
  • Sphere-sphere intersection
  • Sphere-AABB intersection
• Plane: Infinite plane with normal and distance representation
  • Point-plane distance calculation
  • Construction from points/normal
  • Normalization utilities
  • Template-based precision control for construction and normalization
• Frustum: View frustum for efficient visibility culling
  • Fast plane extraction from matrices
  • Comprehensive intersection tests
  • View space utilities

Trigonometry

• Basic Functions: Efficient implementations using lookup tables
  • Sine, cosine, and tangent
  • Arctangent2 with full quadrant support
• Draft Functions: Work-in-progress implementations
  • Inverse trigonometric (asin, acos)
  • Hyperbolic functions (sinh, cosh, tanh)
• Class-Based Interpolation: Each type provides its own specialized interpolation methods
  • Angle class
    • SLerp (spherical linear interpolation) for smooth angle transitions
    • Automatic shortest-path selection
  • Fxp class
    • Lerp (linear interpolation)
    • Smoothstep for smooth acceleration and deceleration (3t² - 2t³)
    • Smootherstep for even smoother transitions (6t⁵ - 15t⁴ + 10t³)
    • EaseIn/Out (quadratic) for accelerating/decelerating motion
    • CubicEaseIn/Out for stronger acceleration/deceleration
    • ElasticEaseIn for spring-like motion
    • BounceEaseIn/Out for bouncing ball effects
    • CubicBezier for custom ea