From 9843d38b67e5e516920ce36a36446ba0183e399c Mon Sep 17 00:00:00 2001 From: Christophe Riccio Date: Fri, 14 Oct 2011 17:05:47 +0100 Subject: [PATCH] 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