From 177e0158b709c3ce24e9b4c0cd3d6d038fc5db14 Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Fri, 14 Oct 2011 16:45:48 +0100 Subject: [PATCH 1/3] 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); From 9843d38b67e5e516920ce36a36446ba0183e399c Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Fri, 14 Oct 2011 17:05:47 +0100 Subject: [PATCH 2/3] Improved documentation --- glm/core/func_geometric.hpp | 22 +++++- glm/core/func_integer.hpp | 142 +++++++++++++++++++++--------------- 2 files changed, 102 insertions(+), 62 deletions(-) diff --git a/glm/core/func_geometric.hpp b/glm/core/func_geometric.hpp index 9cea45de..de6bcf39 100644 --- a/glm/core/func_geometric.hpp +++ b/glm/core/func_geometric.hpp @@ -43,6 +43,8 @@ namespace glm /// Returns the length of x, i.e., sqrt(x * x). /// + /// @tparam genType Floating-point vector types. + /// /// @see - GLSL length man page /// @see - GLSL 4.20.8 specification, section 8.5 template @@ -50,6 +52,8 @@ namespace glm genType const & x); /// Returns the distance betwwen p0 and p1, i.e., length(p0 - p1). + /// + /// @tparam genType Floating-point vector types. /// /// @see - GLSL distance man page /// @see - GLSL 4.20.8 specification, section 8.5 @@ -59,6 +63,8 @@ namespace glm genType const & p1); /// Returns the dot product of x and y, i.e., result = x * y. + /// + /// @tparam genType Floating-point vector types. /// /// @see - GLSL dot man page /// @see - GLSL 4.20.8 specification, section 8.5 @@ -68,13 +74,15 @@ namespace glm genType const & y); /// Returns the cross product of x and y. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL cross man page /// @see - GLSL 4.20.8 specification, section 8.5 - template - detail::tvec3 cross( - detail::tvec3 const & x, - detail::tvec3 const & y); + template + detail::tvec3 cross( + detail::tvec3 const & x, + detail::tvec3 const & y); /// Returns a vector in the same direction as x but with length of 1. /// @@ -85,6 +93,8 @@ namespace glm genType const & x); /// If dot(Nref, I) < 0.0, return N, otherwise, return -N. + /// + /// @tparam genType Floating-point vector types. /// /// @see - GLSL faceforward man page /// @see - GLSL 4.20.8 specification, section 8.5 @@ -96,6 +106,8 @@ namespace glm /// For the incident vector I and surface orientation N, /// returns the reflection direction : result = I - 2.0 * dot(N, I) * N. + /// + /// @tparam genType Floating-point vector types. /// /// @see - GLSL reflect man page /// @see - GLSL 4.20.8 specification, section 8.5 @@ -107,6 +119,8 @@ namespace glm /// For the incident vector I and surface normal N, /// and the ratio of indices of refraction eta, /// return the refraction vector. + /// + /// @tparam genType Floating-point vector types. /// /// @see - GLSL refract man page /// @see - GLSL 4.20.8 specification, section 8.5 diff --git a/glm/core/func_integer.hpp b/glm/core/func_integer.hpp index 6f30d4f2..33613aa2 100644 --- a/glm/core/func_integer.hpp +++ b/glm/core/func_integer.hpp @@ -43,10 +43,12 @@ namespace glm /// @addtogroup core_func_integer /// @{ - //! Adds 32-bit unsigned integer x and y, returning the sum - //! modulo pow(2, 32). The value carry is set to 0 if the sum was - //! less than pow(2, 32), or to 1 otherwise. - //! + /// Adds 32-bit unsigned integer x and y, returning the sum + /// modulo pow(2, 32). The value carry is set to 0 if the sum was + /// less than pow(2, 32), or to 1 otherwise. + /// + /// @tparam genUType Unsigned integer scalar or vector types. + /// /// @see - GLSL uaddCarry man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -55,10 +57,12 @@ namespace glm genUType const & y, genUType & carry); - //! Subtracts the 32-bit unsigned integer y from x, returning - //! the difference if non-negative, or pow(2, 32) plus the difference - //! otherwise. The value borrow is set to 0 if x >= y, or to 1 otherwise. - //! + /// Subtracts the 32-bit unsigned integer y from x, returning + /// the difference if non-negative, or pow(2, 32) plus the difference + /// otherwise. The value borrow is set to 0 if x >= y, or to 1 otherwise. + /// + /// @tparam genUType Unsigned integer scalar or vector types. + /// /// @see - GLSL usubBorrow man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -67,10 +71,12 @@ namespace glm genUType const & y, genUType & borrow); - //! Multiplies 32-bit integers x and y, producing a 64-bit - //! result. The 32 least-significant bits are returned in lsb. - //! The 32 most-significant bits are returned in msb. - //! + /// Multiplies 32-bit integers x and y, producing a 64-bit + /// result. The 32 least-significant bits are returned in lsb. + /// The 32 most-significant bits are returned in msb. + /// + /// @tparam genUType Unsigned integer scalar or vector types. + /// /// @see - GLSL umulExtended man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -80,10 +86,12 @@ namespace glm genUType & msb, genUType & lsb); - //! Multiplies 32-bit integers x and y, producing a 64-bit - //! result. The 32 least-significant bits are returned in lsb. - //! The 32 most-significant bits are returned in msb. - //! + /// Multiplies 32-bit integers x and y, producing a 64-bit + /// result. The 32 least-significant bits are returned in lsb. + /// The 32 most-significant bits are returned in msb. + /// + /// @tparam genIType Signed integer scalar or vector types. + /// /// @see - GLSL imulExtended man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -93,17 +101,19 @@ namespace glm genIType & msb, genIType & lsb); - //! Extracts bits [offset, offset + bits - 1] from value, - //! returning them in the least significant bits of the result. - //! For unsigned data types, the most significant bits of the - //! result will be set to zero. For signed data types, the - //! most significant bits will be set to the value of bit offset + base – 1. - //! - //! If bits is zero, the result will be zero. The result will be - //! undefined if offset or bits is negative, or if the sum of - //! offset and bits is greater than the number of bits used - //! to store the operand. - //! + /// Extracts bits [offset, offset + bits - 1] from value, + /// returning them in the least significant bits of the result. + /// For unsigned data types, the most significant bits of the + /// result will be set to zero. For signed data types, the + /// most significant bits will be set to the value of bit offset + base – 1. + /// + /// If bits is zero, the result will be zero. The result will be + /// undefined if offset or bits is negative, or if the sum of + /// offset and bits is greater than the number of bits used + /// to store the operand. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL bitfieldExtract man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -112,16 +122,18 @@ namespace glm int const & Offset, int const & Bits); - //! Returns the insertion the bits least-significant bits of insert into base. - //! - //! The result will have bits [offset, offset + bits - 1] taken - //! from bits [0, bits – 1] of insert, and all other bits taken - //! directly from the corresponding bits of base. If bits is - //! zero, the result will simply be base. The result will be - //! undefined if offset or bits is negative, or if the sum of - //! offset and bits is greater than the number of bits used to - //! store the operand. - //! + /// Returns the insertion the bits least-significant bits of insert into base. + /// + /// The result will have bits [offset, offset + bits - 1] taken + /// from bits [0, bits – 1] of insert, and all other bits taken + /// directly from the corresponding bits of base. If bits is + /// zero, the result will simply be base. The result will be + /// undefined if offset or bits is negative, or if the sum of + /// offset and bits is greater than the number of bits used to + /// store the operand. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL bitfieldInsert man page /// @see - GLSL 4.20.8 specification, section 8.8 template @@ -131,40 +143,54 @@ namespace glm int const & Offset, int const & Bits); - //! Returns the reversal of the bits of value. - //! The bit numbered n of the result will be taken from bit (bits - 1) - n of value, - //! where bits is the total number of bits used to represent value. - //! + /// Returns the reversal of the bits of value. + /// The bit numbered n of the result will be taken from bit (bits - 1) - n of value, + /// where bits is the total number of bits used to represent value. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL bitfieldReverse man page /// @see - GLSL 4.20.8 specification, section 8.8 template genIUType bitfieldReverse(genIUType const & value); - //! Returns the number of bits set to 1 in the binary representation of value. - //! + /// Returns the number of bits set to 1 in the binary representation of value. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL bitCount man page /// @see - GLSL 4.20.8 specification, section 8.8 - template class C> - typename C::signed_type bitCount(C const & Value); + /// + /// @todo Clarify the declaration to specify that scalars are suported + template class genIUType> + typename genIUType::signed_type bitCount(genIUType const & Value); - //! Returns the bit number of the least significant bit set to - //! 1 in the binary representation of value. - //! If value is zero, -1 will be returned. - //! + /// Returns the bit number of the least significant bit set to + /// 1 in the binary representation of value. + /// If value is zero, -1 will be returned. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL findLSB man page /// @see - GLSL 4.20.8 specification, section 8.8 - template class C> - typename C::signed_type findLSB(C const & Value); + /// + /// @todo Clarify the declaration to specify that scalars are suported + template class genIUType> + typename genIUType::signed_type findLSB(genIUType const & Value); - //! Returns the bit number of the most significant bit in the binary representation of value. - //! For positive integers, the result will be the bit number of the most significant bit set to 1. - //! For negative integers, the result will be the bit number of the most significant - //! bit set to 0. For a value of zero or negative one, -1 will be returned. - //! + /// Returns the bit number of the most significant bit in the binary representation of value. + /// For positive integers, the result will be the bit number of the most significant bit set to 1. + /// For negative integers, the result will be the bit number of the most significant + /// bit set to 0. For a value of zero or negative one, -1 will be returned. + /// + /// @tparam genIUType Signed or unsigned integer scalar or vector types. + /// /// @see - GLSL findMSB man page /// @see - GLSL 4.20.8 specification, section 8.8 - template class C> - typename C::signed_type findMSB(C const & Value); + /// + /// @todo Clarify the declaration to specify that scalars are suported + template class genIUType> + typename genIUType::signed_type findMSB(genIUType const & Value); /// @} }//namespace glm From 13e16886a3cfa9fb989dfe4cd996cb24091044ba Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Fri, 14 Oct 2011 17:43:06 +0100 Subject: [PATCH 3/3] Improve template paramter documentation --- glm/core/func_integer.hpp | 6 +- glm/core/func_matrix.hpp | 56 +++++++++----- glm/core/func_noise.hpp | 8 ++ glm/core/func_trigonometric.hpp | 116 +++++++++++++++++----------- glm/core/func_vector_relational.hpp | 64 +++++++++------ 5 files changed, 163 insertions(+), 87 deletions(-) diff --git a/glm/core/func_integer.hpp b/glm/core/func_integer.hpp index 33613aa2..5e438dee 100644 --- a/glm/core/func_integer.hpp +++ b/glm/core/func_integer.hpp @@ -161,7 +161,7 @@ namespace glm /// @see - GLSL bitCount man page /// @see - GLSL 4.20.8 specification, section 8.8 /// - /// @todo Clarify the declaration to specify that scalars are suported + /// @todo Clarify the declaration to specify that scalars are suported. template class genIUType> typename genIUType::signed_type bitCount(genIUType const & Value); @@ -174,7 +174,7 @@ namespace glm /// @see - GLSL findLSB man page /// @see - GLSL 4.20.8 specification, section 8.8 /// - /// @todo Clarify the declaration to specify that scalars are suported + /// @todo Clarify the declaration to specify that scalars are suported. template class genIUType> typename genIUType::signed_type findLSB(genIUType const & Value); @@ -188,7 +188,7 @@ namespace glm /// @see - GLSL findMSB man page /// @see - GLSL 4.20.8 specification, section 8.8 /// - /// @todo Clarify the declaration to specify that scalars are suported + /// @todo Clarify the declaration to specify that scalars are suported. template class genIUType> typename genIUType::signed_type findMSB(genIUType const & Value); diff --git a/glm/core/func_matrix.hpp b/glm/core/func_matrix.hpp index d50bbc13..5755020c 100644 --- a/glm/core/func_matrix.hpp +++ b/glm/core/func_matrix.hpp @@ -47,6 +47,8 @@ namespace glm /// Multiply matrix x by matrix y component-wise, i.e., /// result[i][j] is the scalar product of x[i][j] and y[i][j]. + /// + /// @tparam matType Floating-point matrix types. /// /// @see - GLSL matrixCompMult man page /// @see - GLSL 4.20.8 specification, section 8.6 @@ -58,15 +60,21 @@ namespace glm /// Treats the first parameter c as a column vector /// and the second parameter r as a row vector /// and does a linear algebraic matrix multiply c * r. + /// + /// @tparam matType Floating-point matrix types. /// /// @see - GLSL outerProduct man page /// @see - GLSL 4.20.8 specification, section 8.6 + /// + /// @todo Clarify the declaration to specify that matType doesn't have to be provided when used. template matType outerProduct( vecType const & c, vecType const & r); /// Returns the transposed matrix of x + /// + /// @tparam matType Floating-point matrix types. /// /// @see - GLSL transpose man page /// @see - GLSL 4.20.8 specification, section 8.6 @@ -75,52 +83,64 @@ namespace glm matType const & x); /// Return the determinant of a mat2 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL determinant man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - typename detail::tmat2x2::value_type determinant( - detail::tmat2x2 const & m); + template + typename detail::tmat2x2::value_type determinant( + detail::tmat2x2 const & m); /// Return the determinant of a mat3 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL determinant man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - typename detail::tmat3x3::value_type determinant( - detail::tmat3x3 const & m); + template + typename detail::tmat3x3::value_type determinant( + detail::tmat3x3 const & m); /// Return the determinant of a mat4 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL determinant man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - typename detail::tmat4x4::value_type determinant( - detail::tmat4x4 const & m); + template + typename detail::tmat4x4::value_type determinant( + detail::tmat4x4 const & m); /// Return the inverse of a mat2 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL inverse man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - detail::tmat2x2 inverse( - detail::tmat2x2 const & m); + template + detail::tmat2x2 inverse( + detail::tmat2x2 const & m); /// Return the inverse of a mat3 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL inverse man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - detail::tmat3x3 inverse( - detail::tmat3x3 const & m); + template + detail::tmat3x3 inverse( + detail::tmat3x3 const & m); /// Return the inverse of a mat4 matrix. + /// + /// @tparam valType Floating-point scalar types. /// /// @see - GLSL inverse man page /// @see - GLSL 4.20.8 specification, section 8.6 - template - detail::tmat4x4 inverse( - detail::tmat4x4 const & m); + template + detail::tmat4x4 inverse( + detail::tmat4x4 const & m); /// @} }//namespace glm diff --git a/glm/core/func_noise.hpp b/glm/core/func_noise.hpp index 5e095af2..27971729 100644 --- a/glm/core/func_noise.hpp +++ b/glm/core/func_noise.hpp @@ -44,6 +44,8 @@ namespace glm /// @{ /// Returns a 1D noise value based on the input value x. + /// + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL noise1 man page /// @see - GLSL 4.20.8 specification, section 8.13 @@ -51,6 +53,8 @@ namespace glm typename genType::value_type noise1(genType const & x); /// Returns a 2D noise value based on the input value x. + /// + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL noise2 man page /// @see - GLSL 4.20.8 specification, section 8.13 @@ -58,6 +62,8 @@ namespace glm detail::tvec2 noise2(genType const & x); /// Returns a 3D noise value based on the input value x. + /// + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL noise3 man page /// @see - GLSL 4.20.8 specification, section 8.13 @@ -65,6 +71,8 @@ namespace glm detail::tvec3 noise3(genType const & x); /// Returns a 4D noise value based on the input value x. + /// + /// @tparam genType Floating-point scalar or vector types. /// /// @see - GLSL noise4 man page /// @see - GLSL 4.20.8 specification, section 8.13 diff --git a/glm/core/func_trigonometric.hpp b/glm/core/func_trigonometric.hpp index f6e7c98d..f048d43b 100644 --- a/glm/core/func_trigonometric.hpp +++ b/glm/core/func_trigonometric.hpp @@ -45,119 +45,149 @@ namespace glm /// @addtogroup core_func_trigonometric /// @{ - //! Converts degrees to radians and returns the result. - //! + /// Converts degrees to radians and returns the result. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL radians man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType radians(genType const & degrees); - //! Converts radians to degrees and returns the result. - //! + /// Converts radians to degrees and returns the result. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL degrees man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType degrees(genType const & radians); - //! The standard trigonometric sine function. - //! The values returned by this function will range from [-1, 1]. - //! + /// The standard trigonometric sine function. + /// The values returned by this function will range from [-1, 1]. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL sin man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType sin(genType const & angle); - //! The standard trigonometric cosine function. - //! The values returned by this function will range from [-1, 1]. - //! + /// The standard trigonometric cosine function. + /// The values returned by this function will range from [-1, 1]. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL cos man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType cos(genType const & angle); - //! The standard trigonometric tangent function. - //! + /// The standard trigonometric tangent function. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL tan man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType tan(genType const & angle); - //! Arc sine. Returns an angle whose sine is x. - //! The range of values returned by this function is [-PI/2, PI/2]. - //! Results are undefined if |x| > 1. - //! + /// Arc sine. Returns an angle whose sine is x. + /// The range of values returned by this function is [-PI/2, PI/2]. + /// Results are undefined if |x| > 1. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL asin man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType asin(genType const & x); - //! Arc cosine. Returns an angle whose sine is x. - //! The range of values returned by this function is [0, PI]. - //! Results are undefined if |x| > 1. - //! + /// Arc cosine. Returns an angle whose sine is x. + /// The range of values returned by this function is [0, PI]. + /// Results are undefined if |x| > 1. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL acos man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType acos(genType const & x); - //! Arc tangent. Returns an angle whose tangent is y/x. - //! The signs of x and y are used to determine what - //! quadrant the angle is in. The range of values returned - //! by this function is [-PI, PI]. Results are undefined - //! if x and y are both 0. - //! + /// Arc tangent. Returns an angle whose tangent is y/x. + /// The signs of x and y are used to determine what + /// quadrant the angle is in. The range of values returned + /// by this function is [-PI, PI]. Results are undefined + /// if x and y are both 0. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL atan man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType atan(genType const & y, genType const & x); - //! Arc tangent. Returns an angle whose tangent is y_over_x. - //! The range of values returned by this function is [-PI/2, PI/2]. - //! + /// Arc tangent. Returns an angle whose tangent is y_over_x. + /// The range of values returned by this function is [-PI/2, PI/2]. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL atan man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType atan(genType const & y_over_x); - //! Returns the hyperbolic sine function, (exp(x) - exp(-x)) / 2 - //! + /// Returns the hyperbolic sine function, (exp(x) - exp(-x)) / 2 + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL sinh man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType sinh(genType const & angle); - //! Returns the hyperbolic cosine function, (exp(x) + exp(-x)) / 2 - //! + /// Returns the hyperbolic cosine function, (exp(x) + exp(-x)) / 2 + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL cosh man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType cosh(genType const & angle); - //! Returns the hyperbolic tangent function, sinh(angle) / cosh(angle) - //! + /// Returns the hyperbolic tangent function, sinh(angle) / cosh(angle) + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL tanh man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType tanh(genType const & angle); - //! Arc hyperbolic sine; returns the inverse of sinh. - //! + /// Arc hyperbolic sine; returns the inverse of sinh. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL asinh man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType asinh(genType const & x); - //! Arc hyperbolic cosine; returns the non-negative inverse - //! of cosh. Results are undefined if x < 1. - //! + /// Arc hyperbolic cosine; returns the non-negative inverse + /// of cosh. Results are undefined if x < 1. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL acosh man page /// @see - GLSL 4.20.8 specification, section 8.1 template genType acosh(genType const & x); - //! Arc hyperbolic tangent; returns the inverse of tanh. - //! Results are undefined if abs(x) >= 1. - //! + /// Arc hyperbolic tangent; returns the inverse of tanh. + /// Results are undefined if abs(x) >= 1. + /// + /// @tparam genType Floating-point scalar or vector types. + /// /// @see - GLSL atanh man page /// @see - GLSL 4.20.8 specification, section 8.1 template diff --git a/glm/core/func_vector_relational.hpp b/glm/core/func_vector_relational.hpp index a3cce581..1da814b8 100644 --- a/glm/core/func_vector_relational.hpp +++ b/glm/core/func_vector_relational.hpp @@ -48,65 +48,83 @@ namespace glm /// @addtogroup core_func_vector_relational /// @{ - //! Returns the component-wise comparison result of x < y. - //! + /// Returns the component-wise comparison result of x < y. + /// + /// @tparam vecType Floating-point or integer vector types. + /// /// @see - GLSL lessThan man page /// @see - GLSL 4.20.8 specification, section 8.7 - //template class vecType> - //GLM_FUNC_QUALIFIER typename vecType::bool_type lessThan(vecType const & x, vecType const & y); + template + GLM_FUNC_QUALIFIER typename vecType::bool_type lessThan(vecType const & x, vecType const & y); - //! Returns the component-wise comparison of result x <= y. - //! + /// Returns the component-wise comparison of result x <= y. + /// + /// @tparam vecType Floating-point or integer vector types. + /// /// @see - GLSL lessThanEqual man page /// @see - GLSL 4.20.8 specification, section 8.7 template class vecType> GLM_FUNC_QUALIFIER typename vecType::bool_type lessThanEqual(vecType const & x, vecType const & y); - //! Returns the component-wise comparison of result x > y. - //! + /// Returns the component-wise comparison of result x > y. + /// + /// @tparam vecType Floating-point or integer vector types. + /// /// @see - GLSL greaterThan man page /// @see - GLSL 4.20.8 specification, section 8.7 template class vecType> GLM_FUNC_QUALIFIER typename vecType::bool_type greaterThan(vecType const & x, vecType const & y); - //! Returns the component-wise comparison of result x >= y. - //! + /// Returns the component-wise comparison of result x >= y. + /// + /// @tparam vecType Floating-point or integer vector types. + /// /// @see - GLSL greaterThanEqual man page /// @see - GLSL 4.20.8 specification, section 8.7 template class vecType> typename vecType::bool_type greaterThanEqual(vecType const & x, vecType const & y); - //! Returns the component-wise comparison of result x == y. - //! + /// Returns the component-wise comparison of result x == y. + /// + /// @tparam vecType Floating-point, integer or boolean vector types. + /// /// @see - GLSL equal man page /// @see - GLSL 4.20.8 specification, section 8.7 - //template class vecType> - //GLM_FUNC_QUALIFIER typename vecType::bool_type equal(vecType const & x, vecType const & y); + template class vecType> + GLM_FUNC_QUALIFIER typename vecType::bool_type equal(vecType const & x, vecType const & y); - //! Returns the component-wise comparison of result x != y. - //! + /// Returns the component-wise comparison of result x != y. + /// + /// @tparam vecType Floating-point, integer or boolean vector types. + /// /// @see - GLSL notEqual man page /// @see - GLSL 4.20.8 specification, section 8.7 template class vecType> typename vecType::bool_type notEqual(vecType const & x, vecType const & y); - //! Returns true if any component of x is true. - //! + /// Returns true if any component of x is true. + /// + /// @tparam vecType Boolean vector types. + /// /// @see - GLSL any man page /// @see - GLSL 4.20.8 specification, section 8.7 template