MatrixConventionsC.h (6342B)
1 /** @file 2 @brief Header 3 4 Must be c-safe! 5 6 @date 2015 7 8 @author 9 Sensics, Inc. 10 <http://sensics.com/osvr> 11 */ 12 13 /* 14 // Copyright 2015 Sensics, Inc. 15 // 16 // Licensed under the Apache License, Version 2.0 (the "License"); 17 // you may not use this file except in compliance with the License. 18 // You may obtain a copy of the License at 19 // 20 // http://www.apache.org/licenses/LICENSE-2.0 21 // 22 // Unless required by applicable law or agreed to in writing, software 23 // distributed under the License is distributed on an "AS IS" BASIS, 24 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 // See the License for the specific language governing permissions and 26 // limitations under the License. 27 */ 28 29 #ifndef INCLUDED_MatrixConventionsC_h_GUID_6FC7A4C6_E6C5_4A96_1C28_C3D21B909681 30 #define INCLUDED_MatrixConventionsC_h_GUID_6FC7A4C6_E6C5_4A96_1C28_C3D21B909681 31 32 /* Internal Includes */ 33 #include <osvr/Util/Export.h> 34 #include <osvr/Util/APIBaseC.h> 35 #include <osvr/Util/StdInt.h> 36 #include <osvr/Util/Pose3C.h> 37 #include <osvr/Util/ReturnCodesC.h> 38 39 /* Library/third-party includes */ 40 /* none */ 41 42 /* Standard includes */ 43 /* none */ 44 45 OSVR_EXTERN_C_BEGIN 46 47 /** @defgroup MatrixConvention Matrix conventions and bit flags 48 @ingroup UtilMath 49 */ 50 51 /** @brief Type for passing matrix convention flags. 52 @ingroup MatrixConvention 53 */ 54 typedef uint16_t OSVR_MatrixConventions; 55 56 #ifndef OSVR_DOXYGEN_EXTERNAL 57 /** @brief Bitmasks for testing matrix conventions. 58 @ingroup MatrixConvention 59 */ 60 typedef enum OSVR_MatrixMasks { 61 OSVR_MATRIX_MASK_ROWMAJOR = 0x1, 62 OSVR_MATRIX_MASK_ROWVECTORS = 0x2, 63 OSVR_MATRIX_MASK_LHINPUT = 0x4, 64 OSVR_MATRIX_MASK_UNSIGNEDZ = 0x8 65 } OSVR_MatrixMasks; 66 #endif 67 68 /** @defgroup MatrixFlags Matrix flags 69 @ingroup MatrixConvention 70 71 Bit flags for specifying matrix options. Only one option may be specified 72 per enum, with all the specified options combined with bitwise-or `|`. 73 74 Most methods that take matrix flags only obey ::OSVR_MatrixOrderingFlags and 75 ::OSVR_MatrixVectorFlags - the flags that affect memory order. The remaining 76 flags are for use with projection matrix generation API methods. 77 78 @{ 79 */ 80 /** @brief Flag bit controlling output memory order */ 81 typedef enum OSVR_MatrixOrderingFlags { 82 /** @brief Column-major memory order (default) */ 83 OSVR_MATRIX_COLMAJOR = 0x0, 84 /** @brief Row-major memory order */ 85 OSVR_MATRIX_ROWMAJOR = OSVR_MATRIX_MASK_ROWMAJOR 86 } OSVR_MatrixOrderingFlags; 87 88 /** @brief Flag bit controlling expected input to matrices. 89 (Related to ::OSVR_MatrixOrderingFlags - setting one to non-default results 90 in an output change, but setting both to non-default results in effectively 91 no change in the output. If this blows your mind, just ignore this aside and 92 carry on.) 93 */ 94 typedef enum OSVR_MatrixVectorFlags { 95 /** @brief Matrix transforms column vectors (default) */ 96 OSVR_MATRIX_COLVECTORS = 0x0, 97 /** @brief Matrix transforms row vectors */ 98 OSVR_MATRIX_ROWVECTORS = OSVR_MATRIX_MASK_ROWVECTORS 99 } OSVR_MatrixVectorFlags; 100 101 /** @brief Flag bit to indicate coordinate system input to projection matrix */ 102 typedef enum OSVR_ProjectionMatrixInputFlags { 103 /** @brief Matrix takes vectors from a right-handed coordinate system 104 (default) */ 105 OSVR_MATRIX_RHINPUT = 0x0, 106 /** @brief Matrix takes vectors from a left-handed coordinate system */ 107 OSVR_MATRIX_LHINPUT = OSVR_MATRIX_MASK_LHINPUT 108 109 } OSVR_ProjectionMatrixInputFlags; 110 111 /** @brief Flag bit to indicate the desired post-projection Z value convention 112 */ 113 typedef enum OSVR_ProjectionMatrixZFlags { 114 /** @brief Matrix maps the near and far planes to signed Z values (in the 115 range [-1, 1]) (default)*/ 116 OSVR_MATRIX_SIGNEDZ = 0x0, 117 /** @brief Matrix maps the near and far planes to unsigned Z values (in the 118 range [0, 1]) */ 119 OSVR_MATRIX_UNSIGNEDZ = OSVR_MATRIX_MASK_UNSIGNEDZ 120 } OSVR_ProjectionMatrixZFlags; 121 /** @} */ /* end of matrix flags group */ 122 123 enum { 124 /** @brief Constant for the number of elements in the matrices we use - 4x4. 125 @ingroup MatrixConvention 126 */ 127 OSVR_MATRIX_SIZE = 16 128 }; 129 130 /** @addtogroup UtilMath 131 @{ 132 */ 133 /** @brief Set a matrix of doubles based on a Pose3. 134 @param pose The Pose3 to convert 135 @param flags Memory ordering flag - see @ref MatrixFlags 136 @param[out] mat an array of 16 doubles 137 */ 138 OSVR_UTIL_EXPORT OSVR_ReturnCode osvrPose3ToMatrixd( 139 OSVR_Pose3 const* pose, OSVR_MatrixConventions flags, double* mat); 140 141 /** @brief Set a matrix of floats based on a Pose3. 142 @param pose The Pose3 to convert 143 @param flags Memory ordering flag - see @ref MatrixFlags 144 @param[out] mat an array of 16 floats 145 */ 146 OSVR_UTIL_EXPORT OSVR_ReturnCode osvrPose3ToMatrixf( 147 OSVR_Pose3 const* pose, OSVR_MatrixConventions flags, float* mat); 148 /** @} */ 149 150 OSVR_EXTERN_C_END 151 152 #ifdef __cplusplus 153 /** @brief Set a matrix based on a Pose3. (C++-only overload - detecting scalar 154 * type) */ 155 inline OSVR_ReturnCode osvrPose3ToMatrix(OSVR_Pose3 const* pose, 156 OSVR_MatrixConventions flags, 157 double* mat) { 158 return osvrPose3ToMatrixd(pose, flags, mat); 159 } 160 161 /** @brief Set a matrix based on a Pose3. (C++-only overload - detecting scalar 162 * type) */ 163 inline OSVR_ReturnCode osvrPose3ToMatrix(OSVR_Pose3 const* pose, 164 OSVR_MatrixConventions flags, 165 float* mat) { 166 return osvrPose3ToMatrixf(pose, flags, mat); 167 } 168 169 /** @brief Set a matrix based on a Pose3. (C++-only overload - detects scalar 170 * and takes array rather than pointer) */ 171 template <typename Scalar> 172 inline OSVR_ReturnCode osvrPose3ToMatrix(OSVR_Pose3 const* pose, 173 OSVR_MatrixConventions flags, 174 Scalar mat[OSVR_MATRIX_SIZE]) { 175 return osvrPose3ToMatrix(pose, flags, &(mat[0])); 176 } 177 /** @brief Set a matrix based on a Pose3. (C++-only overload - detects scalar, 178 * takes array, takes pose by reference) */ 179 template <typename Scalar> 180 inline OSVR_ReturnCode osvrPose3ToMatrix(OSVR_Pose3 const& pose, 181 OSVR_MatrixConventions flags, 182 Scalar mat[OSVR_MATRIX_SIZE]) { 183 return osvrPose3ToMatrix(&pose, flags, &(mat[0])); 184 } 185 186 #endif 187 188 /** @} */ 189 190 #endif