mirror of
https://github.com/orange-cpp/omath.git
synced 2026-02-13 15:03:27 +00:00
136 lines
3.8 KiB
Markdown
136 lines
3.8 KiB
Markdown
# `omath::unity_engine` — formulas & matrix helpers
|
||
|
||
> Header: `omath/engines/unity_engine/formulas.hpp`
|
||
> Namespace: `omath::unity_engine`
|
||
> Purpose: compute direction vectors, rotation matrices, view matrices, and perspective projections for Unity Engine
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
This header provides **Unity Engine**-specific math for:
|
||
|
||
* **Direction vectors** (`forward`, `right`, `up`) from `ViewAngles`
|
||
* **Rotation matrices** from Euler angles
|
||
* **View matrices** (camera transforms)
|
||
* **Perspective projection** matrices
|
||
|
||
All functions respect Unity Engine's **Y-up, left-handed** coordinate system.
|
||
|
||
---
|
||
|
||
## API
|
||
|
||
```cpp
|
||
namespace omath::unity_engine {
|
||
|
||
// Compute forward direction from pitch/yaw/roll
|
||
[[nodiscard]]
|
||
Vector3<float> forward_vector(const ViewAngles& angles) noexcept;
|
||
|
||
// Compute right direction from pitch/yaw/roll
|
||
[[nodiscard]]
|
||
Vector3<float> right_vector(const ViewAngles& angles) noexcept;
|
||
|
||
// Compute up direction from pitch/yaw/roll
|
||
[[nodiscard]]
|
||
Vector3<float> up_vector(const ViewAngles& angles) noexcept;
|
||
|
||
// Build 3x3 rotation matrix from angles
|
||
[[nodiscard]]
|
||
Mat4X4 rotation_matrix(const ViewAngles& angles) noexcept;
|
||
|
||
// Build view matrix (camera space transform)
|
||
[[nodiscard]]
|
||
Mat4X4 calc_view_matrix(const ViewAngles& angles,
|
||
const Vector3<float>& cam_origin) noexcept;
|
||
|
||
// Build perspective projection matrix
|
||
[[nodiscard]]
|
||
Mat4X4 calc_perspective_projection_matrix(float field_of_view,
|
||
float aspect_ratio,
|
||
float near, float far) noexcept;
|
||
|
||
} // namespace omath::unity_engine
|
||
```
|
||
|
||
---
|
||
|
||
## Direction vectors
|
||
|
||
Given camera angles (pitch/yaw/roll):
|
||
|
||
* `forward_vector(angles)` → unit vector pointing where the camera looks
|
||
* `right_vector(angles)` → unit vector pointing to the camera's right
|
||
* `up_vector(angles)` → unit vector pointing upward relative to the camera
|
||
|
||
These are used for movement, aim direction, and building coordinate frames.
|
||
|
||
---
|
||
|
||
## Rotation & view matrices
|
||
|
||
* `rotation_matrix(angles)` → 3×3 (or 4×4) rotation matrix from Euler angles
|
||
* `calc_view_matrix(angles, origin)` → camera view matrix
|
||
|
||
The view matrix transforms world coordinates into camera space (origin at camera, axes aligned with camera orientation).
|
||
|
||
---
|
||
|
||
## Perspective projection
|
||
|
||
```cpp
|
||
Mat4X4 proj = calc_perspective_projection_matrix(
|
||
fov_degrees, // vertical field of view (e.g., 60)
|
||
aspect_ratio, // width / height (e.g., 16/9)
|
||
near_plane, // e.g., 0.3
|
||
far_plane // e.g., 1000.0
|
||
);
|
||
```
|
||
|
||
Produces a **perspective projection matrix** suitable for 3D rendering pipelines. Combined with the view matrix, this implements the standard camera transform chain.
|
||
|
||
---
|
||
|
||
## Usage example
|
||
|
||
```cpp
|
||
using namespace omath::unity_engine;
|
||
|
||
// Camera setup
|
||
ViewAngles angles = {
|
||
PitchAngle::from_degrees(-15.0f),
|
||
YawAngle::from_degrees(45.0f),
|
||
RollAngle::from_degrees(0.0f)
|
||
};
|
||
Vector3<float> cam_pos{10.0f, 5.0f, -10.0f};
|
||
|
||
// Compute direction
|
||
auto forward = forward_vector(angles);
|
||
auto right = right_vector(angles);
|
||
auto up = up_vector(angles);
|
||
|
||
// Build matrices
|
||
auto view_mat = calc_view_matrix(angles, cam_pos);
|
||
auto proj_mat = calc_perspective_projection_matrix(60.0f, 16.0f/9.0f, 0.3f, 1000.0f);
|
||
|
||
// Use view_mat and proj_mat for rendering...
|
||
```
|
||
|
||
---
|
||
|
||
## Conventions
|
||
|
||
* **Angles**: pitch (up/down), yaw (left/right), roll (tilt)
|
||
* **Pitch**: positive = looking up, negative = looking down
|
||
* **Yaw**: increases counter-clockwise from the +Z axis
|
||
* **Coordinate system**: Y-up, Z-forward, X-right (left-handed)
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
* `omath/engines/unity_engine/constants.hpp` — coordinate frame & angle types
|
||
* `omath/engines/unity_engine/traits/camera_trait.hpp` — plug-in for generic `Camera`
|
||
* `omath/projection/camera.hpp` — generic camera wrapper using these formulas
|