From 62e4c59d8da4b073a6b463fe22386254b17f38ec Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Thu, 30 Aug 2018 01:04:26 +0200 Subject: [PATCH] More manual documentation --- glm/detail/compute_common.hpp | 4 +- glm/detail/func_common.inl | 22 ++++----- manual.md | 90 ++++++++++++++++++++++++++++------- 3 files changed, 86 insertions(+), 30 deletions(-) diff --git a/glm/detail/compute_common.hpp b/glm/detail/compute_common.hpp index 38869912..cc24b9e6 100644 --- a/glm/detail/compute_common.hpp +++ b/glm/detail/compute_common.hpp @@ -16,7 +16,7 @@ namespace detail GLM_FUNC_QUALIFIER GLM_CONSTEXPR static genFIType call(genFIType x) { GLM_STATIC_ASSERT( - std::numeric_limits::is_iec559 || std::numeric_limits::is_signed || GLM_CONFIG_UNRESTRICTED_GENTYPE, + std::numeric_limits::is_iec559 || std::numeric_limits::is_signed, "'abs' only accept floating-point and integer scalar or vector inputs"); return x >= genFIType(0) ? x : -x; @@ -41,7 +41,7 @@ namespace detail GLM_FUNC_QUALIFIER GLM_CONSTEXPR static genFIType call(genFIType x) { GLM_STATIC_ASSERT( - (!std::numeric_limits::is_signed && std::numeric_limits::is_integer) || GLM_CONFIG_UNRESTRICTED_GENTYPE, + (!std::numeric_limits::is_signed && std::numeric_limits::is_integer), "'abs' only accept floating-point and integer scalar or vector inputs"); return x; } diff --git a/glm/detail/func_common.inl b/glm/detail/func_common.inl index 2816b86b..c15ca56d 100644 --- a/glm/detail/func_common.inl +++ b/glm/detail/func_common.inl @@ -15,7 +15,7 @@ namespace glm template GLM_FUNC_QUALIFIER GLM_CONSTEXPR genType min(genType x, genType y) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'min' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'min' only accept floating-point or integer inputs"); return (y < x) ? y : x; } @@ -23,7 +23,7 @@ namespace glm template GLM_FUNC_QUALIFIER GLM_CONSTEXPR genType max(genType x, genType y) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'max' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'max' only accept floating-point or integer inputs"); return (x < y) ? y : x; } @@ -474,7 +474,7 @@ namespace detail template GLM_FUNC_QUALIFIER GLM_CONSTEXPR vec min(vec const& a, T b) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'min' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'min' only accept floating-point or integer inputs"); return detail::compute_min_vector::value>::call(a, vec(b)); } @@ -488,7 +488,7 @@ namespace detail template GLM_FUNC_QUALIFIER GLM_CONSTEXPR vec max(vec const& a, T b) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'max' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'max' only accept floating-point or integer inputs"); return detail::compute_max_vector::value>::call(a, vec(b)); } @@ -502,21 +502,21 @@ namespace detail template GLM_FUNC_QUALIFIER GLM_CONSTEXPR genType clamp(genType x, genType minVal, genType maxVal) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'clamp' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'clamp' only accept floating-point or integer inputs"); return min(max(x, minVal), maxVal); } template GLM_FUNC_QUALIFIER GLM_CONSTEXPR vec clamp(vec const& x, T minVal, T maxVal) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'clamp' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'clamp' only accept floating-point or integer inputs"); return detail::compute_clamp_vector::value>::call(x, vec(minVal), vec(maxVal)); } template GLM_FUNC_QUALIFIER GLM_CONSTEXPR vec clamp(vec const& x, vec const& minVal, vec const& maxVal) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'clamp' only accept floating-point or integer inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || std::numeric_limits::is_integer, "'clamp' only accept floating-point or integer inputs"); return detail::compute_clamp_vector::value>::call(x, minVal, maxVal); } @@ -745,7 +745,7 @@ namespace detail template GLM_FUNC_QUALIFIER genType frexp(genType x, int& exp) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'frexp' only accept floating-point inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559, "'frexp' only accept floating-point inputs"); return std::frexp(x, &exp); } @@ -753,7 +753,7 @@ namespace detail template GLM_FUNC_QUALIFIER vec frexp(vec const& v, vec& exp) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'frexp' only accept floating-point inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559, "'frexp' only accept floating-point inputs"); vec Result; for (length_t l = 0; l < v.length(); ++l) @@ -764,7 +764,7 @@ namespace detail template GLM_FUNC_QUALIFIER genType ldexp(genType const& x, int const& exp) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'ldexp' only accept floating-point inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559, "'ldexp' only accept floating-point inputs"); return std::ldexp(x, exp); } @@ -772,7 +772,7 @@ namespace detail template GLM_FUNC_QUALIFIER vec ldexp(vec const& v, vec const& exp) { - GLM_STATIC_ASSERT(std::numeric_limits::is_iec559 || GLM_CONFIG_UNRESTRICTED_GENTYPE, "'ldexp' only accept floating-point inputs"); + GLM_STATIC_ASSERT(std::numeric_limits::is_iec559, "'ldexp' only accept floating-point inputs"); vec Result; for (length_t l = 0; l < v.length(); ++l) diff --git a/manual.md b/manual.md index 9ab3f702..197b0cf1 100644 --- a/manual.md +++ b/manual.md @@ -661,27 +661,30 @@ void foo(vec4 const& v) ### 2.18. GLM\_FORCE\_UNRESTRICTED\_GENTYPE: Removing genType restriction -By default GLM only supports basic types as genType for vector, matrix and quaternion types: +GLSL has restrictions on types supported by certain functions that may appear excessive. +By default, GLM follows the GLSL specification as accurately as possible however it's possible to relax these rules using GLM\_FORCE\_UNRESTRICTED\_GENTYPE define. ```cpp #include -typedef glm::vec<4, float> my_fvec4; +float average(float const A, float const B) +{ + return glm::mix(A, B, 0.5f); // By default glm::mix only supports floating-point types +} ``` -GLM 0.9.8 introduced GLM\_FORCE\_UNRESTRICTED\_GENTYPE define to relax this restriction: +By defining GLM\_FORCE\_UNRESTRICTED\_GENTYPE, we allow using integer types: ```cpp #define GLM_FORCE_UNRESTRICTED_GENTYPE #include -#include "half.hpp" // Define “half” class with behavior equivalent to “float” - -typedef glm::vec<4, half> my_hvec4; +int average(int const A, int const B) +{ + return glm::mix(A, B, 0.5f); // integers are ok thanks to GLM_FORCE_UNRESTRICTED_GENTYPE +} ``` -However, defining `GLM_FORCE_UNRESTRICTED_GENTYPE` is not compatible with `GLM_FORCE_SWIZZLE` and will generate a compilation error if both are defined at the same time. - --- ## 3. Stable extensions @@ -703,12 +706,12 @@ Include `` to use these features. #### 3.2.1. GLM_EXT_scalar_common -This extension exposes support for `min` and `max` functions taking more than two scalar arguments. Also, it adds `fmin` and `fmax` variants which prevents `NaN` probagation. +This extension exposes support for `min` and `max` functions taking more than two scalar arguments. Also, it adds `fmin` and `fmax` variants which prevents `NaN` propagation. ```cpp #include -float PositiveMax(float const a, float const b) +float positiveMax(float const a, float const b) { return glm::fmax(a, b, 0.0f); } @@ -718,12 +721,12 @@ Include `` to use these features. #### 3.2.2. GLM_EXT_scalar_relational -This extension exposes `equal` and `notEqual` variants which takes an epsilon argument. +This extension exposes `equal` and `notEqual` scalar variants which takes an epsilon argument. ```cpp #include -bool myEqual(float const a, float const b) +bool epsilonEqual(float const a, float const b) { float const CustomEpsilon = 0.0001f; return glm::equal(a, b, CustomEpsilon); @@ -734,7 +737,26 @@ Include `` to use these features. #### 3.2.3. GLM_EXT_scalar_constants -TODO +This extension exposes useful constants such as `epsilon` and `pi`. + +```cpp +#include + +float circumference(float const Diameter) +{ + return glm::pi() * Diameter; +} +``` + +```cpp +#include // abs +#include // epsilon + +bool equalULP1(float const a, float const b) +{ + return glm::abs(a - b) <= glm::epsilon(); +} +``` Include `` to use these features. @@ -764,13 +786,34 @@ TODO #### 3.4.1. GLM_EXT_vector_common -TODO +This extension exposes support for `min` and `max` functions taking more than two vector arguments. Also, it adds `fmin` and `fmax` variants which prevents `NaN` propagation. -Include `` to use these features. +```cpp +#include // vec2 +#include // fmax + +float positiveMax(float const a, float const b) +{ + return glm::fmax(a, b, 0.0f); +} +``` + +Include `` to use these features. #### 3.4.2. GLM_EXT_vector_relational -TODO +This extension exposes `equal` and `notEqual` vector variants which takes an epsilon argument. + +```cpp +#include // vec2 +#include // equal, all + +bool epsilonEqual(glm::vec2 const& A, glm::vec2 const& B) +{ + float const CustomEpsilon = 0.0001f; + return glm::all(glm::equal(A, B, CustomEpsilon)); +} +``` Include `` to use these features. @@ -788,7 +831,20 @@ TODO #### 3.6.1. GLM_EXT_matrix_relational -TODO +This extension exposes `equal` and `notEqual` matrix variants which takes an optional epsilon argument. + +```cpp +#include // bvec4 +#include // mat4 +#include // equal, all + +bool epsilonEqual(glm::mat4 const& A, glm::mat4 const& B) +{ + float const CustomEpsilon = 0.0001f; + glm::bvec4 const ColumnEqual = glm::equal(A, B, CustomEpsilon); // Evaluation per column + return glm::all(ColumnEqual); +} +``` Include `` to use these features.