From 177e0158b709c3ce24e9b4c0cd3d6d038fc5db14 Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Fri, 14 Oct 2011 16:45:48 +0100 Subject: [PATCH] Improve documentation --- glm/core/func_common.hpp | 256 +++++++++++++++++++++------------- glm/core/func_exponential.hpp | 21 +++ glm/gtx/fast_exponential.hpp | 2 +- 3 files changed, 178 insertions(+), 101 deletions(-) diff --git a/glm/core/func_common.hpp b/glm/core/func_common.hpp index 9832319c..1409f9d3 100644 --- a/glm/core/func_common.hpp +++ b/glm/core/func_common.hpp @@ -44,72 +44,90 @@ namespace glm /// @{ /// Returns x if x >= 0; otherwise, it returns -x. + /// + /// @tparam genType floating-point or signed integer; scalar or vector types. /// /// @see - GLSL abs man page /// @see - GLSL 4.20.8 specification, section 8.3 - template - genFIType abs(genFIType const & x); + template + genType abs(genType const & x); /// Returns 1.0 if x > 0, 0.0 if x == 0, or -1.0 if x < 0. - /// + /// + /// @tparam genType Floating-point or signed integer; scalar or vector types. + /// /// @see - GLSL sign man page /// @see - GLSL 4.20.8 specification, section 8.3 - template - genFIType sign(genFIType const & x); + template + genType sign(genType const & x); - //! Returns a value equal to the nearest integer that is less then or equal to x. - //! + /// Returns a value equal to the nearest integer that is less then or equal to x. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL floor man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType floor(genType const & x); - //! Returns a value equal to the nearest integer to x - //! whose absolute value is not larger than the absolute value of x. - //! + /// Returns a value equal to the nearest integer to x + /// whose absolute value is not larger than the absolute value of x. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL trunc man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType trunc(genType const & x); - //! Returns a value equal to the nearest integer to x. - //! The fraction 0.5 will round in a direction chosen by the - //! implementation, presumably the direction that is fastest. - //! This includes the possibility that round(x) returns the - //! same value as roundEven(x) for all values of x. - //! + /// Returns a value equal to the nearest integer to x. + /// The fraction 0.5 will round in a direction chosen by the + /// implementation, presumably the direction that is fastest. + /// This includes the possibility that round(x) returns the + /// same value as roundEven(x) for all values of x. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL round man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType round(genType const & x); - //! Returns a value equal to the nearest integer to x. - //! A fractional part of 0.5 will round toward the nearest even - //! integer. (Both 3.5 and 4.5 for x will return 4.0.) - //! + /// Returns a value equal to the nearest integer to x. + /// A fractional part of 0.5 will round toward the nearest even + /// integer. (Both 3.5 and 4.5 for x will return 4.0.) + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL roundEven man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType roundEven(genType const & x); - //! Returns a value equal to the nearest integer - //! that is greater than or equal to x. - //! + /// Returns a value equal to the nearest integer + /// that is greater than or equal to x. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL ceil man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType ceil(genType const & x); - //! Return x - floor(x). - //! + /// Return x - floor(x). + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL fract man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType fract(genType const & x); - //! Modulus. Returns x - y * floor(x / y) - //! for each component in x using the floating point value y. - //! + /// Modulus. Returns x - y * floor(x / y) + /// for each component in x using the floating point value y. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL mod man page /// @see - GLSL 4.20.8 specification, section 8.3 template @@ -117,9 +135,11 @@ namespace glm genType const & x, genType const & y); - //! Modulus. Returns x - y * floor(x / y) - //! for each component in x using the floating point value y. - //! + /// Modulus. Returns x - y * floor(x / y) + /// for each component in x using the floating point value y. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL mod man page /// @see - GLSL 4.20.8 specification, section 8.3 template @@ -127,11 +147,13 @@ namespace glm genType const & x, typename genType::value_type const & y); - //! Returns the fractional part of x and sets i to the integer - //! part (as a whole number floating point value). Both the - //! return value and the output parameter will have the same - //! sign as x. - //! + /// Returns the fractional part of x and sets i to the integer + /// part (as a whole number floating point value). Both the + /// return value and the output parameter will have the same + /// sign as x. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL modf man page /// @see - GLSL 4.20.8 specification, section 8.3 template @@ -140,6 +162,8 @@ namespace glm genType & i); /// Returns y if y < x; otherwise, it returns x. + /// + /// @tparam genType Floating-point or integer; scalar or vector types. /// /// @see - GLSL min man page /// @see - GLSL 4.20.8 specification, section 8.3 @@ -154,6 +178,8 @@ namespace glm typename genType::value_type const & y); /// Returns y if x < y; otherwise, it returns x. + /// + /// @tparam genType Floating-point or integer; scalar or vector types. /// /// @see - GLSL max man page /// @see - GLSL 4.20.8 specification, section 8.3 @@ -167,9 +193,11 @@ namespace glm genType const & x, typename genType::value_type const & y); - //! Returns min(max(x, minVal), maxVal) for each component in x - //! using the floating-point values minVal and maxVal. - //! + /// Returns min(max(x, minVal), maxVal) for each component in x + /// using the floating-point values minVal and maxVal. + /// + /// @tparam genType Floating-point or integer; scalar or vector types. + /// /// @see - GLSL clamp man page /// @see - GLSL 4.20.8 specification, section 8.3 template @@ -243,16 +271,18 @@ namespace glm typename genType::value_type const & edge, genType const & x); - //! Returns 0.0 if x <= edge0 and 1.0 if x >= edge1 and - //! performs smooth Hermite interpolation between 0 and 1 - //! when edge0 < x < edge1. This is useful in cases where - //! you would want a threshold function with a smooth - //! transition. This is equivalent to: - //! genType t; - //! t = clamp ((x – edge0) / (edge1 – edge0), 0, 1); - //! return t * t * (3 – 2 * t); - //! Results are undefined if edge0 >= edge1. - //! + /// Returns 0.0 if x <= edge0 and 1.0 if x >= edge1 and + /// performs smooth Hermite interpolation between 0 and 1 + /// when edge0 < x < edge1. This is useful in cases where + /// you would want a threshold function with a smooth + /// transition. This is equivalent to: + /// genType t; + /// t = clamp ((x – edge0) / (edge1 – edge0), 0, 1); + /// return t * t * (3 – 2 * t); + /// Results are undefined if edge0 >= edge1. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL smoothstep man page /// @see - GLSL 4.20.8 specification, section 8.3 template @@ -267,97 +297,123 @@ namespace glm typename genType::value_type const & edge1, genType const & x); - //! Returns true if x holds a NaN (not a number) - //! representation in the underlying implementation's set of - //! floating point representations. Returns false otherwise, - //! including for implementations with no NaN - //! representations. - //! + /// Returns true if x holds a NaN (not a number) + /// representation in the underlying implementation's set of + /// floating point representations. Returns false otherwise, + /// including for implementations with no NaN + /// representations. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL isnan man page /// @see - GLSL 4.20.8 specification, section 8.3 template typename genType::bool_type isnan(genType const & x); - //! Returns true if x holds a positive infinity or negative - //! infinity representation in the underlying implementation's - //! set of floating point representations. Returns false - //! otherwise, including for implementations with no infinity - //! representations. - //! + /// Returns true if x holds a positive infinity or negative + /// infinity representation in the underlying implementation's + /// set of floating point representations. Returns false + /// otherwise, including for implementations with no infinity + /// representations. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL isinf man page /// @see - GLSL 4.20.8 specification, section 8.3 template typename genType::bool_type isinf(genType const & x); - //! Returns a signed integer value representing - //! the encoding of a floating-point value. The floatingpoint - //! value's bit-level representation is preserved. - //! + /// Returns a signed integer value representing + /// the encoding of a floating-point value. The floatingpoint + /// value's bit-level representation is preserved. + /// + /// @tparam genType Single-precision floating-point scalar or vector types. + /// @tparam genIType Signed integer scalar or vector types. + /// /// @see - GLSL floatBitsToInt man page /// @see - GLSL 4.20.8 specification, section 8.3 template genIType floatBitsToInt(genType const & value); - //! Returns a unsigned integer value representing - //! the encoding of a floating-point value. The floatingpoint - //! value's bit-level representation is preserved. - //! + /// Returns a unsigned integer value representing + /// the encoding of a floating-point value. The floatingpoint + /// value's bit-level representation is preserved. + /// + /// @tparam genType Single-precision floating-point scalar or vector types. + /// @tparam genUType Unsigned integer scalar or vector types. + /// /// @see - GLSL floatBitsToUint man page /// @see - GLSL 4.20.8 specification, section 8.3 template genUType floatBitsToUint(genType const & value); - //! Returns a floating-point value corresponding to a signed - //! integer encoding of a floating-point value. - //! If an inf or NaN is passed in, it will not signal, and the - //! resulting floating point value is unspecified. Otherwise, - //! the bit-level representation is preserved. - //! + /// Returns a floating-point value corresponding to a signed + /// integer encoding of a floating-point value. + /// If an inf or NaN is passed in, it will not signal, and the + /// resulting floating point value is unspecified. Otherwise, + /// the bit-level representation is preserved. + /// + /// @tparam genType Single-precision floating-point scalar or vector types. + /// @tparam genIType Signed integer scalar or vector types. + /// /// @see - GLSL intBitsToFloat man page /// @see - GLSL 4.20.8 specification, section 8.3 + /// + /// @todo - Clarify this declaration, we don't need to actually specify the return type template genType intBitsToFloat(genIType const & value); - //! Returns a floating-point value corresponding to a - //! unsigned integer encoding of a floating-point value. - //! If an inf or NaN is passed in, it will not signal, and the - //! resulting floating point value is unspecified. Otherwise, - //! the bit-level representation is preserved. - //! + /// Returns a floating-point value corresponding to a + /// unsigned integer encoding of a floating-point value. + /// If an inf or NaN is passed in, it will not signal, and the + /// resulting floating point value is unspecified. Otherwise, + /// the bit-level representation is preserved. + /// + /// @tparam genType Single-precision floating-point scalar or vector types. + /// @tparam genUType Unsigned integer scalar or vector types. + /// /// @see - GLSL uintBitsToFloat man page /// @see - GLSL 4.20.8 specification, section 8.3 + /// + /// @todo - Clarify this declaration, we don't need to actually specify the return type template genType uintBitsToFloat(genUType const & value); - //! Computes and returns a * b + c. - //! + /// Computes and returns a * b + c. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL fma man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType fma(genType const & a, genType const & b, genType const & c); - //! Splits x into a floating-point significand in the range - //! [0.5, 1.0) and an integral exponent of two, such that: - //! x = significand * exp(2, exponent) - //! - //! The significand is returned by the function and the - //! exponent is returned in the parameter exp. For a - //! floating-point value of zero, the significant and exponent - //! are both zero. For a floating-point value that is an - //! infinity or is not a number, the results are undefined. - //! + /// Splits x into a floating-point significand in the range + /// [0.5, 1.0) and an integral exponent of two, such that: + /// x = significand * exp(2, exponent) + /// + /// The significand is returned by the function and the + /// exponent is returned in the parameter exp. For a + /// floating-point value of zero, the significant and exponent + /// are both zero. For a floating-point value that is an + /// infinity or is not a number, the results are undefined. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL frexp man page /// @see - GLSL 4.20.8 specification, section 8.3 template genType frexp(genType const & x, genIType & exp); - //! Builds a floating-point number from x and the - //! corresponding integral exponent of two in exp, returning: - //! significand * exp(2, exponent) - //! - //! If this product is too large to be represented in the - //! floating-point type, the result is undefined. - //! + /// Builds a floating-point number from x and the + /// corresponding integral exponent of two in exp, returning: + /// significand * exp(2, exponent) + /// + /// If this product is too large to be represented in the + /// floating-point type, the result is undefined. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL ldexp man page; /// @see - GLSL 4.20.8 specification, section 8.3 template diff --git a/glm/core/func_exponential.hpp b/glm/core/func_exponential.hpp index b59f191f..b36a13ad 100644 --- a/glm/core/func_exponential.hpp +++ b/glm/core/func_exponential.hpp @@ -42,6 +42,9 @@ namespace glm /// @{ /// Returns x raised to the y power. + /// + /// @param x pow function is defined for input values of x defined in the range (inf-, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL pow man page /// @see - GLSL 4.20.8 specification, section 8.2 @@ -49,6 +52,9 @@ namespace glm genType pow(genType const & x, genType const & y); /// Returns the natural exponentiation of x, i.e., e^x. + /// + /// @param x exp function is defined for input values of x defined in the range (inf-, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL exp man page /// @see - GLSL 4.20.8 specification, section 8.2 @@ -58,6 +64,9 @@ namespace glm /// Returns the natural logarithm of x, i.e., /// returns the value y which satisfies the equation x = e^y. /// Results are undefined if x <= 0. + /// + /// @param x log function is defined for input values of x defined in the range (0, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL log man page /// @see - GLSL 4.20.8 specification, section 8.2 @@ -65,6 +74,9 @@ namespace glm genType log(genType const & x); /// Returns 2 raised to the x power. + /// + /// @param x exp2 function is defined for input values of x defined in the range (inf-, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL exp2 man page /// @see - GLSL 4.20.8 specification, section 8.2 @@ -74,6 +86,9 @@ namespace glm /// Returns the base 2 log of x, i.e., returns the value y, /// which satisfies the equation x = 2 ^ y. /// + /// @param x log2 function is defined for input values of x defined in the range (0, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL log2 man page /// @see - GLSL 4.20.8 specification, section 8.2 template @@ -81,6 +96,9 @@ namespace glm /// Returns the positive square root of x. /// + /// @param x sqrt function is defined for input values of x defined in the range [0, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL sqrt man page /// @see - GLSL 4.20.8 specification, section 8.2 template @@ -88,6 +106,9 @@ namespace glm /// Returns the reciprocal of the positive square root of x. /// + /// @param x inversesqrt function is defined for input values of x defined in the range [0, inf+) in the limit of the type precision. + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL inversesqrt man page /// @see - GLSL 4.20.8 specification, section 8.2 template diff --git a/glm/gtx/fast_exponential.hpp b/glm/gtx/fast_exponential.hpp index 83cda03a..b8c3cb58 100644 --- a/glm/gtx/fast_exponential.hpp +++ b/glm/gtx/fast_exponential.hpp @@ -62,7 +62,7 @@ namespace glm //! Faster than the common pow function but less accurate. //! From GLM_GTX_fast_exponential extension. template - genType fastPow( + genTypeT fastPow( genTypeT const & x, genTypeU const & y);