Home | History | Annotate | Download | only in detail 
      1 ///////////////////////////////////////////////////////////////////////////////////
      2 /// OpenGL Mathematics (glm.g-truc.net)
      3 ///
      4 /// Copyright (c) 2005 - 2014 G-Truc Creation (www.g-truc.net)
      5 /// Permission is hereby granted, free of charge, to any person obtaining a copy
      6 /// of this software and associated documentation files (the "Software"), to deal
      7 /// in the Software without restriction, including without limitation the rights
      8 /// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      9 /// copies of the Software, and to permit persons to whom the Software is
     10 /// furnished to do so, subject to the following conditions:
     11 ///
     12 /// The above copyright notice and this permission notice shall be included in
     13 /// all copies or substantial portions of the Software.
     14 ///
     15 /// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     16 /// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     17 /// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     18 /// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     19 /// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
     20 /// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
     21 /// THE SOFTWARE.
     22 ///
     23 /// @ref core
     24 /// @file glm/core/func_integer.hpp
     25 /// @date 2010-03-17 / 2011-06-18
     26 /// @author Christophe Riccio
     27 ///
     28 /// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
     29 ///
     30 /// @defgroup core_func_integer Integer functions
     31 /// @ingroup core
     32 ///
     33 /// These all operate component-wise. The description is per component.
     34 /// The notation [a, b] means the set of bits from bit-number a through bit-number
     35 /// b, inclusive. The lowest-order bit is bit 0.
     36 ///////////////////////////////////////////////////////////////////////////////////
     37 
     38 #ifndef glm_core_func_integer
     39 #define glm_core_func_integer
     40 
     41 #include "setup.hpp"
     42 
     43 namespace glm
     44 {
     45 	/// @addtogroup core_func_integer
     46 	/// @{
     47 
     48 	/// Adds 32-bit unsigned integer x and y, returning the sum
     49 	/// modulo pow(2, 32). The value carry is set to 0 if the sum was
     50 	/// less than pow(2, 32), or to 1 otherwise.
     51 	///
     52 	/// @tparam genUType Unsigned integer scalar or vector types.
     53 	///
     54 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/uaddCarry.xml">GLSL uaddCarry man page</a>
     55 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
     56 	template <typename genUType>
     57 	GLM_FUNC_DECL genUType uaddCarry(
     58 		genUType const & x,
     59 		genUType const & y,
     60 		genUType & carry);
     61 
     62 	/// Subtracts the 32-bit unsigned integer y from x, returning
     63 	/// the difference if non-negative, or pow(2, 32) plus the difference
     64 	/// otherwise. The value borrow is set to 0 if x >= y, or to 1 otherwise.
     65 	///
     66 	/// @tparam genUType Unsigned integer scalar or vector types.
     67 	///
     68 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/usubBorrow.xml">GLSL usubBorrow man page</a>
     69 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
     70 	template <typename genUType>
     71 	GLM_FUNC_DECL genUType usubBorrow(
     72 		genUType const & x,
     73 		genUType const & y,
     74 		genUType & borrow);
     75 
     76 	/// Multiplies 32-bit integers x and y, producing a 64-bit
     77 	/// result. The 32 least-significant bits are returned in lsb.
     78 	/// The 32 most-significant bits are returned in msb.
     79 	///
     80 	/// @tparam genUType Unsigned integer scalar or vector types.
     81 	///
     82 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/umulExtended.xml">GLSL umulExtended man page</a>
     83 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
     84 	template <typename genUType>
     85 	GLM_FUNC_DECL void umulExtended(
     86 		genUType const & x,
     87 		genUType const & y,
     88 		genUType & msb,
     89 		genUType & lsb);
     90 
     91 	/// Multiplies 32-bit integers x and y, producing a 64-bit
     92 	/// result. The 32 least-significant bits are returned in lsb.
     93 	/// The 32 most-significant bits are returned in msb.
     94 	///
     95 	/// @tparam genIType Signed integer scalar or vector types.
     96 	///
     97 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/imulExtended.xml">GLSL imulExtended man page</a>
     98 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
     99 	template <typename genIType>
    100 	GLM_FUNC_DECL void imulExtended(
    101 		genIType const & x,
    102 		genIType const & y,
    103 		genIType & msb,
    104 		genIType & lsb);
    105 
    106 	/// Extracts bits [offset, offset + bits - 1] from value,
    107 	/// returning them in the least significant bits of the result.
    108 	/// For unsigned data types, the most significant bits of the
    109 	/// result will be set to zero. For signed data types, the
    110 	/// most significant bits will be set to the value of bit offset + base - 1.
    111 	///
    112 	/// If bits is zero, the result will be zero. The result will be
    113 	/// undefined if offset or bits is negative, or if the sum of
    114 	/// offset and bits is greater than the number of bits used
    115 	/// to store the operand.
    116 	///
    117 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    118 	///
    119 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/bitfieldExtract.xml">GLSL bitfieldExtract man page</a>
    120 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    121 	template <typename genIUType>
    122 	GLM_FUNC_DECL genIUType bitfieldExtract(
    123 		genIUType const & Value,
    124 		int const & Offset,
    125 		int const & Bits);
    126 
    127 	/// Returns the insertion the bits least-significant bits of insert into base.
    128 	///
    129 	/// The result will have bits [offset, offset + bits - 1] taken
    130 	/// from bits [0, bits - 1] of insert, and all other bits taken
    131 	/// directly from the corresponding bits of base. If bits is
    132 	/// zero, the result will simply be base. The result will be
    133 	/// undefined if offset or bits is negative, or if the sum of
    134 	/// offset and bits is greater than the number of bits used to
    135 	/// store the operand.
    136 	///
    137 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    138 	///
    139 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/bitfieldInsert.xml">GLSL bitfieldInsert man page</a>
    140 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    141 	template <typename genIUType>
    142 	GLM_FUNC_DECL genIUType bitfieldInsert(
    143 		genIUType const & Base,
    144 		genIUType const & Insert,
    145 		int const & Offset,
    146 		int const & Bits);
    147 
    148 	/// Returns the reversal of the bits of value.
    149 	/// The bit numbered n of the result will be taken from bit (bits - 1) - n of value,
    150 	/// where bits is the total number of bits used to represent value.
    151 	///
    152 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    153 	///
    154 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/bitfieldReverse.xml">GLSL bitfieldReverse man page</a>
    155 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    156 	template <typename genIUType>
    157 	GLM_FUNC_DECL genIUType bitfieldReverse(genIUType const & Value);
    158 
    159 	/// Returns the number of bits set to 1 in the binary representation of value.
    160 	///
    161 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    162 	///
    163 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/bitCount.xml">GLSL bitCount man page</a>
    164 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    165 	///
    166 	/// @todo Clarify the declaration to specify that scalars are suported.
    167 	template <typename T, template <typename> class genIUType>
    168 	GLM_FUNC_DECL typename genIUType<T>::signed_type bitCount(genIUType<T> const & Value);
    169 
    170 	/// Returns the bit number of the least significant bit set to
    171 	/// 1 in the binary representation of value.
    172 	/// If value is zero, -1 will be returned.
    173 	///
    174 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    175 	///
    176 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/findLSB.xml">GLSL findLSB man page</a>
    177 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    178 	///
    179 	/// @todo Clarify the declaration to specify that scalars are suported.
    180 	template <typename T, template <typename> class genIUType>
    181 	GLM_FUNC_DECL typename genIUType<T>::signed_type findLSB(genIUType<T> const & Value);
    182 
    183 	/// Returns the bit number of the most significant bit in the binary representation of value.
    184 	/// For positive integers, the result will be the bit number of the most significant bit set to 1.
    185 	/// For negative integers, the result will be the bit number of the most significant
    186 	/// bit set to 0. For a value of zero or negative one, -1 will be returned.
    187 	///
    188 	/// @tparam genIUType Signed or unsigned integer scalar or vector types.
    189 	///
    190 	/// @see <a href="http://www.opengl.org/sdk/docs/manglsl/xhtml/findMSB.xml">GLSL findMSB man page</a>
    191 	/// @see <a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.20.8.pdf">GLSL 4.20.8 specification, section 8.8 Integer Functions</a>
    192 	///
    193 	/// @todo Clarify the declaration to specify that scalars are suported.
    194 	template <typename T, template <typename> class genIUType>
    195 	GLM_FUNC_DECL typename genIUType<T>::signed_type findMSB(genIUType<T> const & Value);
    196 
    197 	/// @}
    198 }//namespace glm
    199 
    200 #include "func_integer.inl"
    201 
    202 #endif//glm_core_func_integer
    203 
    204