mirror of
https://github.com/orange-cpp/omath.git
synced 2026-06-08 16:24:35 +00:00
Moves images to improved documentation structure
Moves various image files demonstrating libomath’s usage and featuring artwork from showcases to the improved `docs/images` structure to reorganize the project's documentation in a logical and maintainable fashion. This change ensures consistency and simplifies updating documentation assets.
This commit is contained in:
BIN
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+67
-60
@@ -1,68 +1,75 @@
|
||||
# Installation
|
||||
<div class="center-text">
|
||||
<!-- Banner -->
|
||||
<p>
|
||||
<img src="images/logos/omath_logo_macro.png" alt="omath banner">
|
||||
</p>
|
||||
|
||||
## <img width="28px" src="https://vcpkg.io/assets/mark/mark.svg" /> Using vcpkg
|
||||
**Note**: Support vcpkg for package management
|
||||
1. Install [vcpkg](https://github.com/microsoft/vcpkg)
|
||||
2. Run the following command to install the orange-math package:
|
||||
```
|
||||
vcpkg install orange-math
|
||||
```
|
||||
CMakeLists.txt
|
||||
```cmake
|
||||
find_package(omath CONFIG REQUIRED)
|
||||
target_link_libraries(main PRIVATE omath::omath)
|
||||
```
|
||||
For detailed commands on installing different versions and more information, please refer to Microsoft's [official instructions](https://learn.microsoft.com/en-us/vcpkg/get_started/overview).
|
||||
<!-- Badges -->
|
||||
<p>
|
||||
<img src="https://img.shields.io/badge/license-libomath-orange" alt="license: libomath">
|
||||
<img src="https://img.shields.io/github/contributors/orange-cpp/omath" alt="GitHub contributors">
|
||||
<img src="https://img.shields.io/github/languages/top/orange-cpp/omath" alt="Top language">
|
||||
<a href="https://www.codefactor.io/repository/github/orange-cpp/omath">
|
||||
<img src="https://www.codefactor.io/repository/github/orange-cpp/omath/badge" alt="CodeFactor">
|
||||
</a>
|
||||
<img src="https://img.shields.io/github/actions/workflow/status/orange-cpp/omath/cmake-multi-platform.yml" alt="GitHub Actions Workflow Status">
|
||||
<a href="https://repology.org/project/orange-math/versions">
|
||||
<img src="https://repology.org/badge/version-for-repo/vcpkg/orange-math.svg" alt="Vcpkg package">
|
||||
</a>
|
||||
<img src="https://img.shields.io/github/forks/orange-cpp/omath" alt="GitHub forks">
|
||||
<a href="https://discord.gg/eDgdaWbqwZ">
|
||||
<img src="https://dcbadge.limes.pink/api/server/https://discord.gg/eDgdaWbqwZ?style=flat" alt="Join us on Discord">
|
||||
</a>
|
||||
<a href="https://t.me/orangennotes">
|
||||
<img src="https://img.shields.io/badge/Telegram-2CA5E0?style=flat-squeare&logo=telegram&logoColor=white" alt="Telegram">
|
||||
</a>
|
||||
</p>
|
||||
</div>
|
||||
OMath is a 100% independent, constexpr template blazingly fast math library that doesn't have legacy C++ code.
|
||||
|
||||
## <img width="28px" src="https://xmake.io/assets/img/logo.svg" /> Using xrepo
|
||||
**Note**: Support xrepo for package management
|
||||
1. Install [xmake](https://xmake.io/)
|
||||
2. Run the following command to install the omath package:
|
||||
```
|
||||
xrepo install omath
|
||||
```
|
||||
xmake.lua
|
||||
```xmake
|
||||
add_requires("omath")
|
||||
target("...")
|
||||
add_packages("omath")
|
||||
```
|
||||
It provides the latest features, is highly customizable, has all for cheat development, DirectX/OpenGL/Vulkan support, premade support for different game engines, much more constexpr stuff than in other libraries and more...
|
||||
|
||||
## <img width="28px" src="https://upload.wikimedia.org/wikipedia/commons/e/ef/CMake_logo.svg?" /> Build from source using CMake
|
||||
1. **Preparation**
|
||||
|
||||
Install needed tools: cmake, clang, git, msvc (windows only).
|
||||
# Features
|
||||
- **Efficiency**: Optimized for performance, ensuring quick computations using AVX2.
|
||||
- **Versatility**: Includes a wide array of mathematical functions and algorithms.
|
||||
- **Ease of Use**: Simplified interface for convenient integration into various projects.
|
||||
- **Projectile Prediction**: Projectile prediction engine with O(N) algo complexity, that can power you projectile aim-bot.
|
||||
- **3D Projection**: No need to find view-projection matrix anymore you can make your own projection pipeline.
|
||||
- **Collision Detection**: Production ready code to handle collision detection by using simple interfaces.
|
||||
- **No Additional Dependencies**: No additional dependencies need to use OMath except unit test execution
|
||||
- **Ready for meta-programming**: Omath use templates for common types like Vectors, Matrixes etc, to handle all types!
|
||||
- **Engine support**: Supports coordinate systems of **Source, Unity, Unreal, Frostbite, IWEngine and canonical OpenGL**.
|
||||
- **Cross platform**: Supports Windows, MacOS and Linux.
|
||||
- **Algorithms**: Has ability to scan for byte pattern with wildcards in PE files/modules, binary slices, works even with Wine apps.
|
||||
|
||||
1. **Linux:**
|
||||
```bash
|
||||
sudo pacman -Sy cmake ninja clang git
|
||||
```
|
||||
2. **MacOS:**
|
||||
```bash
|
||||
brew install llvm git cmake ninja
|
||||
```
|
||||
3. **Windows:**
|
||||
# Gallery
|
||||
|
||||
Install Visual Studio from [here](https://visualstudio.microsoft.com/downloads/) and Git from [here](https://git-scm.com/downloads).
|
||||
<br>
|
||||
|
||||
Use x64 Native Tools shell to execute needed commands down below.
|
||||
2. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/orange-cpp/omath.git
|
||||
```
|
||||
3. **Navigate to the project directory:**
|
||||
```bash
|
||||
cd omath
|
||||
```
|
||||
4. **Build the project using CMake:**
|
||||
```bash
|
||||
cmake --preset windows-release -S .
|
||||
cmake --build cmake-build/build/windows-release --target omath -j 6
|
||||
```
|
||||
Use **\<platform\>-\<build configuration\>** preset to build suitable version for yourself. Like **windows-release** or **linux-release**.
|
||||
[](https://youtu.be/lM_NJ1yCunw?si=-Qf5yzDcWbaxAXGQ)
|
||||
|
||||
| Platform Name | Build Config |
|
||||
|---------------|---------------|
|
||||
| windows | release/debug |
|
||||
| linux | release/debug |
|
||||
| darwin | release/debug |
|
||||
<br>
|
||||
|
||||
![APEX Preview]
|
||||
|
||||
<br>
|
||||
|
||||
![BO2 Preview]
|
||||
|
||||
<br>
|
||||
|
||||
![CS2 Preview]
|
||||
|
||||
<br>
|
||||
|
||||
![TF2 Preview]
|
||||
|
||||
<br>
|
||||
<br>
|
||||
|
||||
<!----------------------------------{ Images }--------------------------------->
|
||||
[APEX Preview]: images/showcase/apex.png
|
||||
[BO2 Preview]: images/showcase/cod_bo2.png
|
||||
[CS2 Preview]: images/showcase/cs2.jpeg
|
||||
[TF2 Preview]: images/showcase/tf2.jpg
|
||||
@@ -0,0 +1,68 @@
|
||||
# Installation
|
||||
|
||||
## <img width="28px" src="https://vcpkg.io/assets/mark/mark.svg" /> Using vcpkg
|
||||
**Note**: Support vcpkg for package management
|
||||
1. Install [vcpkg](https://github.com/microsoft/vcpkg)
|
||||
2. Run the following command to install the orange-math package:
|
||||
```
|
||||
vcpkg install orange-math
|
||||
```
|
||||
CMakeLists.txt
|
||||
```cmake
|
||||
find_package(omath CONFIG REQUIRED)
|
||||
target_link_libraries(main PRIVATE omath::omath)
|
||||
```
|
||||
For detailed commands on installing different versions and more information, please refer to Microsoft's [official instructions](https://learn.microsoft.com/en-us/vcpkg/get_started/overview).
|
||||
|
||||
## <img width="28px" src="https://xmake.io/assets/img/logo.svg" /> Using xrepo
|
||||
**Note**: Support xrepo for package management
|
||||
1. Install [xmake](https://xmake.io/)
|
||||
2. Run the following command to install the omath package:
|
||||
```
|
||||
xrepo install omath
|
||||
```
|
||||
xmake.lua
|
||||
```xmake
|
||||
add_requires("omath")
|
||||
target("...")
|
||||
add_packages("omath")
|
||||
```
|
||||
|
||||
## <img width="28px" src="https://upload.wikimedia.org/wikipedia/commons/e/ef/CMake_logo.svg?" /> Build from source using CMake
|
||||
1. **Preparation**
|
||||
|
||||
Install needed tools: cmake, clang, git, msvc (windows only).
|
||||
|
||||
1. **Linux:**
|
||||
```bash
|
||||
sudo pacman -Sy cmake ninja clang git
|
||||
```
|
||||
2. **MacOS:**
|
||||
```bash
|
||||
brew install llvm git cmake ninja
|
||||
```
|
||||
3. **Windows:**
|
||||
|
||||
Install Visual Studio from [here](https://visualstudio.microsoft.com/downloads/) and Git from [here](https://git-scm.com/downloads).
|
||||
|
||||
Use x64 Native Tools shell to execute needed commands down below.
|
||||
2. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/orange-cpp/omath.git
|
||||
```
|
||||
3. **Navigate to the project directory:**
|
||||
```bash
|
||||
cd omath
|
||||
```
|
||||
4. **Build the project using CMake:**
|
||||
```bash
|
||||
cmake --preset windows-release -S .
|
||||
cmake --build cmake-build/build/windows-release --target omath -j 6
|
||||
```
|
||||
Use **\<platform\>-\<build configuration\>** preset to build suitable version for yourself. Like **windows-release** or **linux-release**.
|
||||
|
||||
| Platform Name | Build Config |
|
||||
|---------------|---------------|
|
||||
| windows | release/debug |
|
||||
| linux | release/debug |
|
||||
| darwin | release/debug |
|
||||
@@ -0,0 +1,4 @@
|
||||
/* docs/css/custom.css */
|
||||
.center-text {
|
||||
text-align: center;
|
||||
}
|
||||
@@ -45,7 +45,7 @@ The pattern string is parsed into a sequence of byte **tokens**:
|
||||
* **Wildcard byte**: `?` or `??` matches **any single byte**.
|
||||
* **Separators**: any ASCII whitespace (space, tab, newline) is **ignored** and may be used to group tokens.
|
||||
|
||||
> ✔️ Valid: `"48 8B ?? 05 00"`, `"90 90 90"`, `"??"`, `"00??FF"` (no spaces)
|
||||
> ✔️ Valid: `"48 8B ?? 05 00"`, `"90 90 90"`, `"??"`
|
||||
> ❌ Invalid: odd number of hex digits in a token, non-hex characters (besides `?` and whitespace)
|
||||
|
||||
If the string cannot be parsed into a clean sequence of tokens, `parse_pattern()` returns `std::unexpected(PatternScanError::INVALID_PATTERN_STRING)`, and the public scan function returns **end**.
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
# `omath::PePatternScanner` — Scan PE images for byte patterns
|
||||
|
||||
> Header: your project’s `pe_pattern_scanner.hpp`
|
||||
> Namespace: `omath`
|
||||
> Platform: **Windows / PE (Portable Executable) images**
|
||||
> Depends on: `<filesystem>`, `<optional>`, `<cstdint>`
|
||||
> Companion: works well with `omath::PatternScanner` (same pattern grammar)
|
||||
|
||||
`PePatternScanner` searches **Portable Executable (PE)** binaries for a hex pattern (with wildcards). You can scan:
|
||||
|
||||
* a **loaded module** in the current process, or
|
||||
* a **PE file on disk** (by section name; defaults to **`.text`**).
|
||||
|
||||
---
|
||||
|
||||
## Pattern string grammar (same as `PatternScanner`)
|
||||
|
||||
* **Hex byte**: two hex digits → one byte (`90`, `4F`, `00`, `ff`).
|
||||
* **Wildcard byte**: `?` or `??` matches **any byte**.
|
||||
* **Whitespace**: ignored (use to group tokens).
|
||||
|
||||
✔️ `"48 8B ?? ?? 89"`, `"55 8B EC"`, `"??"`
|
||||
❌ odd digit counts, non-hex characters (besides `?` and whitespace)
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
```cpp
|
||||
namespace omath {
|
||||
|
||||
struct PeSectionScanResult {
|
||||
std::uint64_t virtual_base_addr; // RVA base of the scanned section (ImageBase + SectionRVA)
|
||||
std::uint64_t raw_base_addr; // file offset (start of section in the file)
|
||||
std::ptrdiff_t target_offset; // offset from section base to the first matched byte
|
||||
};
|
||||
|
||||
class PePatternScanner final {
|
||||
public:
|
||||
// Scan a module already loaded in *this* process.
|
||||
// module_base_address: HMODULE / ImageBase (e.g., from GetModuleHandle)
|
||||
// Returns absolute address (process VA) of the first match, or nullopt.
|
||||
static std::optional<std::uintptr_t>
|
||||
scan_for_pattern_in_loaded_module(const void* module_base_address,
|
||||
const std::string_view& pattern);
|
||||
|
||||
// Scan a PE file on disk, by section name (default ".text").
|
||||
// Returns section bases (virtual + raw) and match offset within the section, or nullopt.
|
||||
static std::optional<PeSectionScanResult>
|
||||
scan_for_pattern_in_file(const std::filesystem::path& path_to_file,
|
||||
const std::string_view& pattern,
|
||||
const std::string_view& target_section_name = ".text");
|
||||
};
|
||||
|
||||
} // namespace omath
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Return values
|
||||
|
||||
* **Loaded module**: `std::optional<std::uintptr_t>`
|
||||
|
||||
* `value()` = **process virtual address** (ImageBase + SectionRVA + match offset).
|
||||
* `nullopt` = no match or parse/PE error.
|
||||
|
||||
* **File scan**: `std::optional<PeSectionScanResult>`
|
||||
|
||||
* `virtual_base_addr` = **ImageBase + SectionRVA** of the scanned section (as if mapped).
|
||||
* `raw_base_addr` = **file offset** of section start.
|
||||
* `target_offset` = offset from the section base to the **first matched byte**.
|
||||
* To get addresses:
|
||||
|
||||
* **Virtual (RVA)** of hit = `virtual_base_addr + target_offset`
|
||||
* **Raw file offset** of hit = `raw_base_addr + target_offset`
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
|
||||
### Scan a loaded module (current process)
|
||||
|
||||
```cpp
|
||||
#include <windows.h>
|
||||
#include "pe_pattern_scanner.hpp"
|
||||
|
||||
using omath::PePatternScanner;
|
||||
|
||||
auto hMod = ::GetModuleHandleW(L"kernel32.dll");
|
||||
if (hMod) {
|
||||
auto addr = PePatternScanner::scan_for_pattern_in_loaded_module(
|
||||
hMod, "48 8B ?? ?? 89" // hex + wildcards
|
||||
);
|
||||
if (addr) {
|
||||
// Use the absolute process VA:
|
||||
std::uintptr_t hit_va = *addr;
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Scan a PE file on disk (default section “.text”)
|
||||
|
||||
```cpp
|
||||
#include "pe_pattern_scanner.hpp"
|
||||
using omath::PePatternScanner;
|
||||
|
||||
auto res = PePatternScanner::scan_for_pattern_in_file(
|
||||
R"(C:\Windows\System32\kernel32.dll)", "55 8B EC"
|
||||
);
|
||||
if (res) {
|
||||
auto rva_hit = res->virtual_base_addr + res->target_offset;
|
||||
auto raw_hit = res->raw_base_addr + res->target_offset;
|
||||
// rva_hit: where it would be in memory; raw_hit: file offset
|
||||
}
|
||||
```
|
||||
|
||||
### Scan another section (e.g., “.rdata”)
|
||||
|
||||
```cpp
|
||||
auto res = PePatternScanner::scan_for_pattern_in_file(
|
||||
"foo.dll", "48 8D 0D ?? ?? ?? ??", ".rdata"
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes & edge cases
|
||||
|
||||
* **PE only**: these functions assume a valid **PE/COFF** layout. Non-PE files or corrupted headers yield `nullopt`.
|
||||
* **Section name**: `scan_for_pattern_in_file` defaults to **`.text`**; pass a different name to target other sections.
|
||||
* **Alignment & RVAs**: `virtual_base_addr` is computed from section headers (RVA aligned per section alignment). The returned “virtual” base is suitable for RVA math; the **process VA** returned by the “loaded module” API already includes the image base.
|
||||
* **Architecture**: works for 32-bit and 64-bit PEs; `std::uintptr_t` size matches the build architecture.
|
||||
* **Performance**: Pattern matching is **O(N × M)** (sliding window with wildcards). For large images, prefer scanning only necessary sections.
|
||||
* **Wildcards**: Each `?` matches **one byte** (no nibble masks). If you need `A?`-style nibble wildcards, extend the parser (see `PatternScanner`).
|
||||
* **Safety**: For loaded modules, you must have access to the memory; scanning read-only sections is fine, but never write. For file scans, ensure the file path is accessible.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* **`nullopt`**: Verify the pattern (valid tokens), correct **section**, and that you’re scanning the intended module/file (check bitness and version).
|
||||
* **“Loaded module” address math**: If you need an **offset from the module base**, compute `offset = hit_va - reinterpret_cast<std::uintptr_t>(module_base_address)`.
|
||||
* **Multiple matches**: Only the **first** match is returned. If you need all matches, extend the implementation to continue scanning from `target_offset + 1`.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
* `omath::PatternScanner` — raw buffer/iterator scanning with the same pattern grammar.
|
||||
* `omath::Triangle`, `omath::Vector3` — math types used elsewhere in the library.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 31 Oct 2025*
|
||||
Reference in New Issue
Block a user