feat: expand configurable FixedPoint<I,F> across entire library and standardize Doxygen - #13
Open
robertoduarte wants to merge 2 commits into
Open
feat: expand configurable FixedPoint<I,F> across entire library and standardize Doxygen#13robertoduarte wants to merge 2 commits into
robertoduarte wants to merge 2 commits into
Conversation
…tandardize Doxygen Extend the configurable FixedPoint<I, F> template to all math types — vectors, matrices, planes, spheres, AABBs, frustums, and collision functions — so every geometric type is parameterized by integer/fractional bit widths and can operate in any fixed-point format. Geometric type templation: - Vector2<I,F> and Vector3<I,F> replace the monomorphic Vector2D/Vector3D structs. Vector3 no longer inherits from Vector2; both are standalone with their own X/Y(/Z) members, eliminating slicing issues and simplifying template parameterization. - Matrix3x3<I,F> and Matrix4x3<I,F> replace Matrix33/Matrix43. Matrix4x3 no longer inherits from Matrix3x3; it composes a 3x3 rotation block and a separate translation row, avoiding diamond-inheritance problems when both are parameterized. - PlaneX<I,F>, SphereX<I,F>, AABBX<I,F>, FrustumX<I,F>, and Collision functions are all templated. Bare aliases (Vector2D, Vector3D, Matrix33, AABB, Sphere, Plane, Frustum) are preserved as synonyms for the default Q16.16 format. Hardware abstraction layer: - Extract all SH-2 inline assembly from fxp.hpp into new hardware.hpp (DIVU registers, 64-bit MAC multiplication, xtrct extraction, arithmetic shifts) with constexpr fallbacks for compile-time evaluation. Math files now contain only portable C++ logic. - Extract integer square root implementations into new integer.hpp (FastSqrt32/FastSqrt64), used by FixedPoint::Sqrt and vector Length(). - Add new constmath.hpp with constexpr-only math functions (Sqrt, Sin, Cos, Tan, Atan, Atan2) for compile-time contexts where hardware intrinsics are unavailable. FixedPoint changes: - Add InternalSqrtFrom64: format-agnostic 64-bit sqrt for vector Length() using MAC register output (hi/lo pair), replacing per-vector inline asm. - Add ConvertUnchecked: silent conversion overload for cases where the caller knows the value fits, bypassing the [[deprecated]] warning. - Add ParallelDiv API: free function + proxy type that overlaps CPU work with the hardware DIVU, replacing the deprecated AsyncDivSet/Get pair. - Change RawValue() to return by value instead of const ref for register passing on SH-2. - Annotate all operators with [[gnu::always_inline]] for consistent codegen. - Rename format aliases to include explicit bit layout: Fxp16->Fxp16_16, Fxp8->Fxp24_8, Fxp24->Fxp8_24. - Add FixedPointType concept for SFINAE/constraint use. Trigonometry rewrite: - Restructure LookupCache with explicit mask/shift template params. - Move table generation to detail namespace with MakeLookupTable helper. - Rebuild Sin/Tan/Atan2 tables with format-aware entry types. - Make all functions constexpr-compatible via constmath fallbacks. - Simplify Precision enum (remove Accurate/Fast/Turbo modes from most functions; TurboLength kept as a named method on vectors). Doxygen standardization: - Apply uniform Doxygen across all impl/ files with @brief, @details, @param, @return, @note, /**< and @name groups for consistent API documentation. Test suite reorganization: - Split multi-format tests into dedicated test_constmath.hpp, test_integer.hpp, test_utils.hpp. - Merge test_aabb_edge_cases.cpp into test_aabb.hpp and delete the standalone file. - Update all test files to use new templated type names.
…al Dot overflow Extract32: replace logical shifts (shlr) with ArithmeticShiftRight in the shift>16 branch. The previous shlr instructions zero-filled the sign bit after xtrct, corrupting negative fixed-point products (e.g. -0.333 became +255.7). This was the root cause of catastrophic normalization errors for vectors with negative components, which made 3D objects invisible when the camera viewed them from certain angles. Also fix consteval Dot product in Vector2D and Vector3D to use int64_t intermediate accumulation, preventing overflow in compile-time constant expressions.
ReyeMe
requested changes
Jul 16, 2026
ReyeMe
left a comment
ReyeMe
left a comment
Collaborator
There was a problem hiding this comment.
Few documentation comments are missing, otherwise looks good
| // Sin table — 64 entries, 10-bit interpolation, 8.24 internal format | ||
| // ================================================================ | ||
|
|
||
| struct SinSpec |
Collaborator
There was a problem hiding this comment.
missing documentation of the struct and its members
| SinSpec::interpolationMask, | ||
| SinSpec::extractShift>; | ||
|
|
||
| constexpr SinEntry BuildSinEntry(int index) |
| // Range: 0 to 0x3C00 (0° to 84.375°), step = 1024 raw units | ||
| // ================================================================ | ||
|
|
||
| struct Tan1Spec |
Collaborator
There was a problem hiding this comment.
missing documentation of the struct and its members
| Tan1Spec::interpolationMask, | ||
| Tan1Spec::extractShift>; | ||
|
|
||
| constexpr Tan1Entry BuildTan1Entry(int index) |
| }; | ||
| } | ||
|
|
||
| inline constexpr auto tanTable1 = MakeLookupTable<Tan1Entry, Tan1Spec::entryCount, BuildTan1Entry>(); |
| }; | ||
| } | ||
|
|
||
| inline constexpr auto tanTable5 = MakeLookupTable<Tan5Entry, Tan5Spec::entryCount, BuildTan5Entry>(); |
| // Maps ratio [0, 1] to angle [0, π/4] in turns | ||
| // ================================================================ | ||
|
|
||
| struct Atan2Spec |
Collaborator
There was a problem hiding this comment.
missing documentation of the struct and its members
| Atan2Spec::interpolationMask, | ||
| Atan2Spec::extractShift>; | ||
|
|
||
| constexpr Atan2Entry BuildAtan2Entry(int index) |
| return { value, static_cast<uint16_t>(multiplicand) }; | ||
| } | ||
|
|
||
| inline constexpr auto atan2Table = MakeLookupTable<Atan2Entry, Atan2Spec::entryCount, BuildAtan2Entry>(); |
| */ | ||
| class Trigonometry final | ||
| { | ||
| private: |
Collaborator
There was a problem hiding this comment.
private members are missing documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Extend the configurable FixedPoint<I, F> template to all math types — vectors, matrices, planes, spheres, AABBs, frustums, and collision functions — so every geometric type is parameterized by integer/fractional bit widths and can operate in any fixed-point format.
Geometric type templation:
Vector2<I,F> and Vector3<I,F> replace the monomorphic Vector2D/Vector3D structs. Vector3 no longer inherits from Vector2; both are standalone with their own X/Y(/Z) members, eliminating slicing issues and simplifying template parameterization.
Matrix3x3<I,F> and Matrix4x3<I,F> replace Matrix33/Matrix43. Matrix4x3 no longer inherits from Matrix3x3; it composes a 3x3 rotation block and a separate translation row, avoiding diamond-inheritance problems when both are parameterized.
PlaneX<I,F>, SphereX<I,F>, AABBX<I,F>, FrustumX<I,F>, and Collision functions are all templated. Bare aliases (Vector2D, Vector3D, Matrix33, AABB, Sphere, Plane, Frustum) are preserved as synonyms for the default Q16.16 format.
Hardware abstraction layer:
Extract all SH-2 inline assembly from fxp.hpp into new hardware.hpp (DIVU registers, 64-bit MAC multiplication, xtrct extraction, arithmetic shifts) with constexpr fallbacks for compile-time evaluation. Math files now contain only portable C++ logic.
Extract integer square root implementations into new integer.hpp (FastSqrt32/FastSqrt64), used by FixedPoint::Sqrt and vector Length().
Add new constmath.hpp with constexpr-only math functions (Sqrt, Sin, Cos, Tan, Atan, Atan2) for compile-time contexts where hardware intrinsics are unavailable.
FixedPoint changes:
Add InternalSqrtFrom64: format-agnostic 64-bit sqrt for vector Length() using MAC register output (hi/lo pair), replacing per-vector inline asm.
Add ConvertUnchecked: silent conversion overload for cases where the caller knows the value fits, bypassing the [[deprecated]] warning.
Add ParallelDiv API: free function + proxy type that overlaps CPU work with the hardware DIVU, replacing the deprecated AsyncDivSet/Get pair.
Change RawValue() to return by value instead of const ref for register passing on SH-2.
Annotate all operators with [[gnu::always_inline]] for consistent codegen.
Rename format aliases to include explicit bit layout: Fxp16->Fxp16_16, Fxp8->Fxp24_8, Fxp24->Fxp8_24.
Add FixedPointType concept for SFINAE/constraint use.
Trigonometry rewrite:
Doxygen standardization:
Test suite reorganization: