// ===================================================================================================================== // fennec, a free and open source game engine // Copyright © 2025 - 2026 Medusa Slockbower // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // This program is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program. If not, see . // ===================================================================================================================== /// /// \file fennec/math/geometric.h /// \brief \ref fennec_math_geometric /// /// /// \details /// \author Medusa Slockbower /// /// \copyright Copyright © 2025 - 2026 Medusa Slockbower ([GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)) /// /// #ifndef FENNEC_MATH_GEOMETRIC_H #define FENNEC_MATH_GEOMETRIC_H /// /// /// /// \page fennec_math_geometric Geometric /// /// \brief The Geometric Functions defined in the [OpenGL 4.6 Shading Language Specification](https://registry.khronos.org/OpenGL/specs/gl/GLSLangSpec.4.60.pdf). /// /// \code #include \endcode /// /// /// \section fennec_math_geometric_section_functions Geometric Functions /// /// ///

Syntax ///	Description ///
/// \ref fennec::dot "float dot(genFType x, genFType y)" /// \ref fennec::dot "double dot(genDType x, genDType x)" ///	/// \copydoc fennec::dot /// ///
/// \ref fennec::length2 "float length2(genFType x)" /// \ref fennec::length2 "double length2(genDType x)" ///	/// \copydoc fennec::length2 /// ///
/// \ref fennec::length "float length(genFType x)" /// \ref fennec::length "double length(genDType x)" ///	/// \copydoc fennec::length /// ///
/// \ref fennec::distance "float distance(genFType x, genFType y)" /// \ref fennec::distance "double distance(genDType x, genDType x)" ///	/// \copydoc fennec::distance /// ///
/// \ref fennec::normalize "float normalize(genFType x)" /// \ref fennec::normalize "double normalize(genDType x)" ///	/// \copydoc fennec::normalize /// ///
/// \ref fennec::cross "vec3 cross(vec3 x, vec3 y)" /// \ref fennec::cross "dvec3 cross(dvec3 x, dvec3 x)" ///	/// \copydoc fennec::cross /// ///
/// \ref fennec::faceforward "genFType faceforward(genFType N, genFType I, genFType Nref)" /// \ref fennec::faceforward "genDType faceforward(genDType N, genDType I, genDType Nref)" ///	/// \copydoc fennec::faceforward /// ///
/// \ref fennec::reflect "genFType reflect(genFType I, genFType N)" /// \ref fennec::reflect "genDType reflect(genDType I, genDType N)" ///	/// \copydoc fennec::reflect /// ///
/// \ref fennec::refract "genFType refract(genFType N, genFType I, float eta)" /// \ref fennec::refract "genDType refract(genDType N, genDType I, double eta)" ///	/// \copydoc fennec::refract /// ///

/// /// /// #include #include #include namespace fennec { // dot ----------------------------------------------------------------------------------------------------------------- /// /// \brief Returns the dot product of \f$x\f$ and \f$y\f$, i.e., \f$x_0 \cdot y_0 + x_1 \cdot y_1 + \ldots\f$ /// /// \returns the dot product of \f$x\f$ and \f$y\f$, i.e., \f$x_0 \cdot y_0 + x_0 \cdot y_0 + \ldots\f$

/// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$
/// let \f$Y=\left[\begin{array}\\ y_0 \\ y_1 \\ \vdots \\ y_N \end{array}\right]\f$

/// /// then \f$\text{dot}(X, Y)=X \cdot Y^T\f$

/// /// \param x first vector /// \param y second vector template constexpr genType dot(const vector& x, const vector& y) { return ((x[i] * y[i]) + ...); } // length2 ------------------------------------------------------------------------------------------------------------- /// /// \brief Returns the squared length of vector \f$x\f$, i.e., \f$x_0^2 + x_1^2 + \ldots\f$ /// /// \returns the squared length of vector \f$x\f$, i.e., \f$x_0^2 + x_1^2 + \ldots\f$

/// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$

/// /// then \f$\text{length2}(X)=X \cdot X^T\f$

/// /// \param x the vector template constexpr genType length2(const vector& x) { return fennec::dot(x, x); } // length -------------------------------------------------------------------------------------------------------------- /// /// \brief Returns the length of vector \f$x\f$, i.e., \f$\sqrt{x_0^2 + x_1^2 + \ldots}\f$ /// /// \returns the length of vector \f$x\f$, i.e., \f$\sqrt{x_0^2 + x_1^2 + \ldots}\f$

/// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$

/// /// then, \f$\text{length}(X)=\left|\left|X\right|\right|\f$

/// /// \param x the vector template constexpr genType length(const vector& x) { return fennec::sqrt(fennec::length2(x)); } // distance ------------------------------------------------------------------------------------------------------------ /// /// \brief Returns the length of vector \f$x\f$, i.e., \f$\sqrt{x_0^2 + x_1^2 + \ldots}\f$ /// /// \returns the distance between \f$p_0\f$ and \f$p_1\f$, i.e., \f$\left|{p_1-p_0}\right|\f$ /// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$
/// let \f$Y=\left[\begin{array}\\ y_0 \\ y_1 \\ \vdots \\ y_N \end{array}\right]\f$

/// /// then \f$\text{distance}(X, Y)=\left|\left|Y-X\right|\right|\f$

/// /// \param p0 first vector /// \param p1 second vector template constexpr genType distance(const vector& p0, const vector& p1) { return fennec::length(p1 - p0); } // cross --------------------------------------------------------------------------------------------------------------- /// /// \brief Returns the cross product of \f$x\f$ and \f$y\f$, i.e., /// \f$\left({x_1 \cdot y_2 - y_1 \cdot x_2, x_2 \cdot y_0 - y_2 \cdot x_0, x_0 \cdot y_1 - y_0 \cdot x_1}\right)\f$ /// /// \returns the cross product of \f$x\f$ and \f$y\f$, i.e., /// \f$\left({x_1 \cdot y_2 - y_1 \cdot x_2, x_2 \cdot y_0 - y_2 \cdot x_0, x_0 \cdot y_1 - y_0 \cdot x_1}\right)\f$

/// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$
/// let \f$Y=\left[\begin{array}\\ y_0 \\ y_1 \\ \vdots \\ y_N \end{array}\right]\f$

/// /// then \f$\text{cross}(X, Y)=X \times Y\f$

/// /// \param x first vector /// \param y second vector template requires(sizeof...(i) == 3) constexpr vector cross(const vector& x, const vector& y) { return vector(x[1]*y[2]-y[1]*x[2], x[2]*y[0]-y[2]*x[0], x[0]*y[1]-y[0]*x[1]); } // normalize ----------------------------------------------------------------------------------------------------------- /// /// \brief Returns a vector in the same direction as \f$x\f$, but with a length of \f$1\f$, i.e. /// /// \returns a vector in the same direction as \f$x\f$, but with a length of \f$1\f$, i.e.\f$\frac{x}{||x||}\f$

/// \details we can represent this in linear algebra as the following,

/// let \f$X=\left[\begin{array}\\ x_0 \\ x_1 \\ \vdots \\ x_N \end{array}\right]\f$

/// /// then, \f$\text{length}(X)=\frac{X}{\left|\left|X\right|\right|}\f$

/// /// \param x template constexpr vector normalize(const vector& x) { return x * fennec::inversesqrt(fennec::dot(x, x)); } // faceforward --------------------------------------------------------------------------------------------------------- /// /// \brief If \f$\text{dot}(Nref, I)<0\f$ return \f$N\f$, otherwise return \f$-N\f$. /// /// \returns \f$N\f$ if \f$\text{dot}(Nref,I)<0\f$, otherwise, returns \f$-N\f$.

/// /// \param N the vector /// \param I the incident /// \param Nref the reference template constexpr vector faceforward(const vector& N, const vector& I, const vector& Nref) { return fennec::sign(fennec::dot(Nref, I)) * N; } // reflect ------------------------------------------------------------------------------------------------------------- /// /// \brief For the incident vector \f$I\f$ and surface orientation \f$N\f$, returns the reflection direction. /// /// \returns The reflection direction, given the incident vector \f$I\f$ and surface orientation \f$N\f$

/// \details We can express this as,

/// \f$\text{reflect}(I, N) = I - 2 N \cdot \text{dot}(N, I)\f$

/// /// \param I the incident /// \param N the surface orientation template constexpr vector reflect(const vector& I, const vector& N) { return I - genType(2.0) * fennec::dot(N, I) * N; } // refract ------------------------------------------------------------------------------------------------------------- /// /// \brief For the incident vector \f$I\f$ and surface normal \f$N\f$, and the ratio of indices of refraction \f$eta\f$, /// return the refraction vector. /// /// \returns The refraction vector, given the incident vector \f$I\f$, surface normal \f$N\f$, and ratio \f$eta\f$.

/// \details The result is computed by the refraction equation,

/// let \f$k=1.0-eta^2 \cdot (1.0 - \text{dot}(N, I)^2)\f$
/// then, \f$\text{refract}(I, N, eta)=\begin{cases} 0.0 & k<0.0, \\ eta \cdot I - N \cdot (eta \cdot \text{dot}(N, I) + \sqrt{k}) \end{cases}\f$

/// /// \param I the incident /// \param N the surface normal /// \param eta the ratio of indices of refraction template constexpr vector refract(const vector& I, const vector& N, genType eta) { genType ndi = fennec::dot(N, I); genType k = genType(1.0) - eta * eta * (genType(1.0) - ndi * ndi); if (k < 0) return vector(0); return eta * I - N * (eta * ndi + fennec::sqrt(k)); } } #endif // FENNEC_MATH_GEOMETRIC_H