omath C++ Mathematics Framework

The omath::Mat class provides a compile-time, fixed-size matrix implementation. It is designed for high performance with no heap allocations and supports both row-major and column-major storage.

Requirements:

• C++23 is required to use the multi-parameter operator[] (e.g., A[r, c]).
• For AVX2-accelerated multiplication of float or double types, define the macro OMATH_USE_AVX2.

Template Parameters:

• Rows: Number of rows (size_t).
• Columns: Number of columns (size_t).
• Type: Element type (defaults to float).
• StoreType: Storage order using MatStoreType (defaults to MatStoreType::ROW_MAJOR).

#include "mat.hpp"
using omath::Mat;
using omath::MatStoreType;

// 4x4 float, row-major (default)
Mat<4, 4> matrix;

// 4x4 float, column-major
Mat<4, 4, float, MatStoreType::COLUMN_MAJOR> col_major_matrix;

omath is a constexpr template-based framework designed for math, physics, and game development (including reverse engineering and modding).

Key capabilities include:

• Performance: Optimized with AVX2.
• Math & Physics: Projectile prediction (O(N) complexity), 3D projection pipelines, and collision detection.
• Engine Support: Native coordinate system support for Source, Rage, Unity, Unreal, Frostbite, IWEngine, CryEngine, and OpenGL.
• Cross-Platform: Supports Windows, MacOS, and Linux.
• No Dependencies: Requires no additional dependencies except for unit test execution.
• Hooking: omath::hooks::HooksManager simplifies drawing overlays by hooking DirectX and OpenGL swap/present calls.

The omath::unreal_engine namespace provides constants that define the Unreal Engine's Z-up, left-handed coordinate system. This system is characterized by:

• Up: {0, 0, 1} (Z-axis)
• Right: {0, 1, 0} (Y-axis)
• Forward: {1, 0, 0} (X-axis)
• Gravity: Points along -Z (height increases with +Z)
• Handedness: Left-handed (cross product forward × right = up using the left-hand rule)

Use the provided k_abs_* constants to reference the world coordinate frame basis vectors.

namespace omath::unreal_engine {
  constexpr Vector3<float> k_abs_up      = {0, 0, 1};
  constexpr Vector3<float> k_abs_right   = {0, 1, 0};
  constexpr Vector3<float> k_abs_forward = {1, 0, 0};
}

The omath::primitives::Mesh class represents a 3D polygonal mesh with vertex data and transformation capabilities. It stores a Vertex Buffer Object (VBO) for vertex positions in local space and a Vertex Array Object (VAO) for triangular face indices. It supports transformations (position, rotation, scale) that can be mapped to specific engine coordinate systems using a MeshTypeTrait.

// Example of creating a simple tetrahedron mesh
std::vector<Vector3<float>> vertices = {
    {0, 0, 0}, {1, 0, 0}, {0, 1, 0}, {0, 0, 1}
};

std::vector<Vector3<std::size_t>> faces = {
    {0, 1, 2},  // Triangle 1
    {0, 1, 3},  // Triangle 2
    {0, 2, 3},  // Triangle 3
    {1, 2, 3}   // Triangle 4
};

using namespace omath::source_engine;
Mesh tetrahedron(std::move(vertices), std::move(faces));

For performance-critical tasks like projectile prediction, you can choose between an AVX2-optimized engine or a Legacy engine.

• Use AVX2 if: You target modern CPUs (2013+) and need maximum performance (typically 2-4x faster).
• Use Legacy if: You need broad compatibility (older CPUs or ARM) or are unsure of the target hardware.

The API is identical; only the class name changes.

Example:

// Legacy (compatible)
ProjPredEngineLegacy engine;

// AVX2 (faster)
ProjPredEngineAVX2 engine;

When using PredEngineTrait, adhere to the following Source Engine conventions:

• Coordinate System: Z-up (height increases along the Z axis).
• Angles:
  • Pitch: [-89°, +89°] (+89° is straight up, -89° is straight down).
  • Yaw: [-180°, +180°].
• Gravity: Applied downward along the -Z axis.

When using omath::iw_engine, ensure your math adheres to the following IW Engine conventions:

Coordinate System:

• Z-up, right-handed.
• X-forward, Y-right (note: Y is negative in code convention).

Angle Definitions:

• Pitch: Up/Down. Positive = looking up, Negative = looking down.
• Yaw: Left/Right. Increases counter-clockwise from the +X axis.
• Roll: Tilt.

When using omath::source_engine formulas, adhere to the following coordinate and angle conventions:

Coordinate System:

• Orientation: Z-up, right-handed.
• Axes: X-forward, Y-right (note: Y is negative in code convention).

Angle Definitions:

• Pitch: Up/Down. Positive = looking up; Negative = looking down.
• Yaw: Left/Right. Increases counter-clockwise from the +X axis.
• Roll: Tilt.

Thread safety in omath depends on the type being used:

• Vector/Matrix types: Thread-safe due to immutable operations.
• Pattern scanning: Thread-safe (read-only operations).
• Camera: Not thread-safe because it maintains mutable state.
• Memory access: Depends on your OS/process synchronization.

Best Practice: To use a Camera in a multi-threaded environment, ensure each thread has its own instance.

// Safe: each thread gets its own camera
std::vector<std::thread> threads;
for (int i = 0; i < num_threads; ++i) {
    threads.emplace_back([i]() {
        Camera camera = /* create camera */;
        // Use camera in this thread
    });
}