mirror of
https://github.com/orange-cpp/omath.git
synced 2026-02-13 23:13:26 +00:00
78 lines
2.2 KiB
Markdown
78 lines
2.2 KiB
Markdown
# `omath::source_engine` — types & constants
|
||
|
||
> Header: `omath/engines/source_engine/constants.hpp`
|
||
> Namespace: `omath::source_engine`
|
||
> Purpose: define Source Engine coordinate system, matrix types, and angle ranges
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
The **Source Engine** uses a **Z-up, right-handed** coordinate system:
|
||
|
||
* **Up** = `{0, 0, 1}` (Z-axis)
|
||
* **Right** = `{0, -1, 0}` (negative Y-axis)
|
||
* **Forward** = `{1, 0, 0}` (X-axis)
|
||
|
||
Matrices are **row-major**. Angles are **clamped pitch** (±89°) and **normalized yaw/roll** (±180°).
|
||
|
||
---
|
||
|
||
## Constants
|
||
|
||
```cpp
|
||
namespace omath::source_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};
|
||
}
|
||
```
|
||
|
||
These basis vectors define the engine's **world coordinate frame**.
|
||
|
||
---
|
||
|
||
## Matrix types
|
||
|
||
```cpp
|
||
using Mat4X4 = Mat<4, 4, float, MatStoreType::ROW_MAJOR>;
|
||
using Mat3X3 = Mat<4, 4, float, MatStoreType::ROW_MAJOR>;
|
||
using Mat1X3 = Mat<1, 3, float, MatStoreType::ROW_MAJOR>;
|
||
```
|
||
|
||
**Row-major** storage means rows are contiguous in memory. Suitable for CPU-side transforms and typical C++ math libraries.
|
||
|
||
---
|
||
|
||
## Angle types
|
||
|
||
```cpp
|
||
using PitchAngle = Angle<float, -89.f, 89.f, AngleFlags::Clamped>;
|
||
using YawAngle = Angle<float, -180.f, 180.f, AngleFlags::Normalized>;
|
||
using RollAngle = Angle<float, -180.f, 180.f, AngleFlags::Normalized>;
|
||
|
||
using ViewAngles = omath::ViewAngles<PitchAngle, YawAngle, RollAngle>;
|
||
```
|
||
|
||
* **PitchAngle**: clamped to **[-89°, +89°]** (looking down vs. up)
|
||
* **YawAngle**: normalized to **[-180°, +180°]** (horizontal rotation)
|
||
* **RollAngle**: normalized to **[-180°, +180°]** (camera roll)
|
||
|
||
`ViewAngles` bundles all three into a single type for camera/view transforms.
|
||
|
||
---
|
||
|
||
## Coordinate system notes
|
||
|
||
* **Z-up**: gravity points along `-Z`, height increases with `+Z`
|
||
* **Right-handed**: cross product `forward × right = up` holds
|
||
* This matches **Source Engine** (Half-Life 2, TF2, CS:GO, etc.) conventions
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
* `omath/engines/source_engine/formulas.hpp` — view/projection matrix builders
|
||
* `omath/trigonometry/angle.hpp` — angle normalization & clamping helpers
|
||
* `omath/trigonometry/view_angles.hpp` — generic pitch/yaw/roll wrapper
|