Skip to content

FAQ

Common questions and answers about OMath.

General Questions

What is OMath?

OMath is a modern C++ math library designed for game development, graphics programming, and high-performance computing. It provides: - Vector and matrix operations - 3D projection and camera systems - Projectile prediction - Collision detection - Support for multiple game engines (Source, Unity, Unreal, etc.) - Pattern scanning utilities

Why choose OMath over other math libraries?

  • Modern C++: Uses C++20/23 features (concepts, constexpr, std::expected)
  • No legacy code: Built from scratch without legacy baggage
  • Game engine support: Pre-configured for Source, Unity, Unreal, Frostbite, etc.
  • Zero dependencies: No external dependencies needed (except for testing)
  • Performance: AVX2 optimizations available
  • Type safety: Strong typing prevents common errors
  • Cross-platform: Works on Windows, Linux, and macOS

Is OMath suitable for production use?

Yes! OMath is production-ready and used in various projects. It has: - Comprehensive test coverage - Clear error handling - Well-documented API - Active maintenance and community support

Installation & Setup

How do I install OMath?

Three main methods:

vcpkg (recommended):

vcpkg install orange-math

xrepo:

xrepo install omath

From source: See Installation Guide

What are the minimum requirements?

  • Compiler: C++20 support required
  • GCC 10+
  • Clang 11+
  • MSVC 2019 16.10+
  • CMake: 3.15+ (if building from source)
  • Platform: Windows, Linux, or macOS

Do I need C++23?

C++23 is recommended but not required. Some features like std::expected work better with C++23, but fallbacks are available for C++20.

Can I use OMath in a C++17 project?

No, OMath requires C++20 minimum due to use of concepts, constexpr enhancements, and other C++20 features.

Usage Questions

How do I include OMath in my project?

Full library:

#include <omath/omath.hpp>

Specific components:

#include <omath/linear_algebra/vector3.hpp>
#include <omath/engines/source_engine/camera.hpp>

Which game engine should I use?

Choose based on your target game or application:

Engine Use For
Source Engine CS:GO, TF2, CS2, Half-Life, Portal, L4D
Unity Engine Unity games (many indie and mobile games)
Unreal Engine Fortnite, Unreal games
Frostbite Battlefield, Star Wars games (EA titles)
IW Engine Call of Duty series
OpenGL Custom OpenGL applications, generic 3D

How do I switch between engines?

Just change the namespace:

// Source Engine
using namespace omath::source_engine;
Camera cam = /* ... */;

// Unity Engine
using namespace omath::unity_engine;
Camera cam = /* ... */;

Each engine has the same API but different coordinate system handling.

What if my game isn't listed?

Use the OpenGL engine as a starting point - it uses canonical OpenGL conventions. You may need to adjust coordinate transformations based on your specific game.

Performance Questions

Should I use the AVX2 or Legacy engine?

Use AVX2 if: - Target modern CPUs (2013+) - Need maximum performance - Can accept reduced compatibility

Use Legacy if: - Need broad compatibility - Target older CPUs or ARM - Unsure about target hardware

The API is identical - just change the class:

// Legacy (compatible)
ProjPredEngineLegacy engine;

// AVX2 (faster)
ProjPredEngineAVX2 engine;

How much faster is AVX2?

Typically 2-4x faster for projectile prediction calculations, depending on the CPU and specific use case.

Are vector operations constexpr?

Yes! Most operations are constexpr and can be evaluated at compile-time:

constexpr Vector3<float> v{1, 2, 3};
constexpr auto len_sq = v.length_sqr();  // Computed at compile time

Is OMath thread-safe?

  • Immutable operations (vector math, etc.) are thread-safe
  • Mutable state (Camera updates) is NOT thread-safe
  • Use separate instances per thread or synchronize access

Troubleshooting

world_to_screen() always returns nullopt

Check: 1. Is the point behind the camera? Points behind the camera cannot be projected. 2. Are near/far planes correct? Ensure near < far and both are positive. 3. Is FOV valid? FOV should be between 1° and 179°. 4. Are camera angles normalized? Use engine-provided angle types.

Angles are wrapping incorrectly

Use the correct angle type:

// Good: uses proper angle type
PitchAngle pitch = PitchAngle::from_degrees(45.0f);

// Bad: raw float loses normalization
float pitch = 45.0f;

Projection seems mirrored or inverted

You may be using the wrong engine trait. Each engine has different coordinate conventions: - Source/Unity: Z-up - Unreal: Z-up, different handedness - OpenGL: Y-up

Ensure you're using the trait matching your game.

Pattern scanning finds multiple matches

This is normal! Patterns may appear multiple times. Solutions: 1. Make the pattern more specific (more bytes, fewer wildcards) 2. Use additional context (nearby code patterns) 3. Verify each match programmatically

Projectile prediction returns nullopt

Common reasons: 1. Target too fast: Target velocity exceeds projectile speed 2. Out of range: Distance exceeds max flight time 3. Invalid input: Check projectile speed > 0 4. Gravity too strong: Projectile can't reach target height

Compilation errors about std::expected

If using C++20 (not C++23), you may need a backport library like tl::expected:

# CMakeLists.txt
find_package(tl-expected CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE tl::expected)

Or upgrade to C++23 if possible.

Feature Questions

Can I use OMath with DirectX/OpenGL/Vulkan?

Yes! OMath matrices and vectors work with all graphics APIs. Use: - OpenGL: opengl_engine traits - DirectX: Use appropriate engine trait or OpenGL as base - Vulkan: Use OpenGL traits as starting point

Does OMath support quaternions?

Not currently. Quaternion support may be added in future versions. For now, use euler angles (ViewAngles) or convert manually.

Can I extend OMath with custom engine traits?

Yes! Implement the CameraEngineConcept:

class MyEngineTrait {
public:
    static ViewAngles calc_look_at_angle(
        const Vector3<float>& origin,
        const Vector3<float>& target
    );

    static Mat4X4 calc_view_matrix(
        const ViewAngles& angles,
        const Vector3<float>& origin
    );

    static Mat4X4 calc_projection_matrix(
        const FieldOfView& fov,
        const ViewPort& viewport,
        float near, float far
    );
};

// Use with Camera
using MyCamera = Camera<Mat4X4, ViewAngles, MyEngineTrait>;

Does OMath support SIMD for vector operations?

AVX2 support is available for projectile prediction. General vector SIMD may be added in future versions. The library already compiles to efficient code with compiler optimizations enabled.

Can I use OMath for machine learning?

OMath is optimized for game development and graphics, not ML. For machine learning, consider libraries like Eigen or xtensor which are designed for that domain.

Debugging Questions

How do I print vectors?

OMath provides std::formatter support:

#include <format>
#include <iostream>

Vector3<float> v{1, 2, 3};
std::cout << std::format("{}", v) << "\n";  // Prints: [1, 2, 3]

How do I visualize projection problems?

  1. Check if world_to_screen() succeeds
  2. Print camera matrices: cpp auto view = camera.get_view_matrix(); auto proj = camera.get_projection_matrix(); // Print matrix values
  3. Test with known good points (e.g., origin, simple positions)
  4. Verify viewport and FOV values

How can I debug pattern scanning?

PatternView pattern{"48 8B 05 ?? ?? ?? ??"};

// Print pattern details
std::cout << "Pattern length: " << pattern.size() << "\n";
std::cout << "Pattern bytes: ";
for (auto byte : pattern) {
    if (byte.has_value()) {
        std::cout << std::hex << (int)*byte << " ";
    } else {
        std::cout << "?? ";
    }
}
std::cout << "\n";

Contributing

How can I contribute to OMath?

See CONTRIBUTING.md for guidelines. Contributions welcome: - Bug fixes - New features - Documentation improvements - Test coverage - Examples

Where do I report bugs?

GitHub Issues

Please include: - OMath version - Compiler and version - Minimal reproducible example - Expected vs actual behavior

How do I request a feature?

Open a GitHub issue with: - Use case description - Proposed API (if applicable) - Why existing features don't meet your needs

What license does OMath use?

OMath uses a custom "libomath" license. See LICENSE for full details.

Can I use OMath in commercial projects?

Check the LICENSE file for commercial use terms.

Can I use OMath for game cheating/hacking?

OMath is a math library and can be used for various purposes. However: - Using it to cheat in online games may violate game ToS - Creating cheats may be illegal in your jurisdiction - The developers do not condone cheating in online games

Use responsibly and ethically.

Getting Help

Where can I get help?

Is there a Discord/community?

Yes! Join our Discord: https://discord.gg/eDgdaWbqwZ

Are there video tutorials?

Check our YouTube channel for demonstrations and tutorials.

Didn't find your answer?

Last updated: 1 Nov 2025