103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
# Josh's 3D Math Library - J3ML
|
|
|
|
|
|
|
|
Yet Another C++ Math Standard
|
|
|
|
J3ML is a "Modern C++" library designed to provide comprehensive support for 3D mathematical operations commonly used in computer graphics, game development, physics simulations, and related fields. It offers a wide range of functionalities to simplify the implementation of complex mathematical operations in your projects.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
* **Vector Operations:** Comprehensive support for 3D vector operations including addition, subtraction, scalar multiplication, dot product, cross product, normalization, and more.
|
|
* **Matrix Operations:** Efficient implementation of 3x3 and 4x4 matrices with support for common operations such as multiplication, transpose, determinant calculation, and inverse calculation.
|
|
* **Quaternion Operations:** Quaternion manipulation functions including conversion to/from axis-angle representation, quaternion multiplication, normalization, and interpolation (slerp).
|
|
* **Transformation Functions:** Functions for transforming points, vectors, and normals using matrices and quaternions.
|
|
* **Geometric Types:** Support for geometric types such as points, lines, rays, planes, spheres, axis-aligned bounding boxes (AABB), and oriented bounding boxes (OBB).
|
|
* **Algorithms:** Implementation of various algorithms including Gilbert-Johnson-Keerthi (GJK) algorithm for collision detection, random number generator, and more.
|
|
* **Utility Functions:** Additional utilities such as conversion between degrees and radians, random number generation, and common constants.
|
|
|
|
## Coming Soon
|
|
|
|
* **SIMD:** (Single-instruction, multiple-data) utilizes a vectorized instruction set to compute operations on multiple values at once. This is particularly useful in matrix maths.
|
|
* **LUTs:** Compute Lookup-tables for common operations, and bake them into your program via constexpr. (Sin, Cos, Tan, Sqrt, FastInverseSqrt)
|
|
|
|
# Installation
|
|
|
|
We support integration via CMake Package Manager (CPM). It's quite clean and flexible. It's a single CMake script too.
|
|
|
|
Here's what we recommend:
|
|
|
|
Install CPM.cmake to a `cmake` directory in your project root, and add the lines below into your CMakeLists.txt
|
|
|
|
To integrate the package manager:
|
|
```cmake
|
|
include("cmake/CPM.cmake")
|
|
```
|
|
|
|
To automatically download and build J3ML version 3.4.5 (Check releases for new versions!):
|
|
|
|
```cmake
|
|
CPMAddPackage(
|
|
NAME J3ML
|
|
URL https::/git.redacted.cc/josh/J3ML/archive/3.4.5.zip
|
|
)
|
|
```
|
|
Then you should be able to link J3ML to your project like any other library:
|
|
|
|
```cmake
|
|
target_include_directories(MyProgramOrLib PUBLIC ${J3ML_SOURCE_DIR}/include)
|
|
###
|
|
target_link_libraries(MyProgramOrLib PUBLIC J3ML)
|
|
```
|
|
|
|
|
|
# Usage Samples
|
|
|
|
## 2D Vector Operations
|
|
|
|
```cpp
|
|
#include <J3ML/LinearAlgebra.hpp>
|
|
|
|
Vector2 position {10.f, 10.f};
|
|
Vector2 velocity {5.f, 1.5f};
|
|
float step = 1.f/60.f;
|
|
|
|
void doStep() {
|
|
position = position + (velocity * step);
|
|
velocity = velocity.Lerp(Vector2::Zero, step);
|
|
float speed = velocity.Length();
|
|
}
|
|
```
|
|
|
|
## Matrix3x3 and Rotation Types
|
|
|
|
```cpp
|
|
#include <j3ml/LinearAlgebra.h>
|
|
|
|
Matrix3x3 mRotation = Matrix3x3::RotateX(Math::PiOverTwo);
|
|
Quaternion qRotation(mRotation); // Convert to Quaternion
|
|
AxisAngle aRotation(qRotation); // Convert to AxisAngle
|
|
EulerAngleXYZ eRotation(aRotation); // Convert to Euler Angle (XYZ)
|
|
```
|
|
|
|
For more detailed usage instructions and examples, please refer to the documentation.
|
|
# Documentation
|
|
|
|
Documentation is automatically generated from latest commit and is hosted at https://doc.redacted.cc/j3ml .
|
|
|
|
# Contributing
|
|
|
|
Contributions to J3ML are welcome! If you find a bug, have a feature request, or would like to contribute code, please submit an issue or pull request to the repository.
|
|
|
|
# License
|
|
|
|
J3ML is licensed under the Public Domain. See the LICENSE file for details.
|
|
|
|
# Acknowledgements
|
|
|
|
J3ML is developed and maintained by Joshua O'Leary from Redacted Software and contributors. Special thanks to William J Tomasine II.
|
|
|
|
bump :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3
|