1 /*! \file features.h 2 * \brief Control compile-time and run-time selectable library features 3 * 4 * \version $Id: features.h,v 1.8 2007/10/10 15:41:58 matt-beard Exp $ 5 * 6 * \detail 7 * Library feature selection allows the behaviour of the library to be modified at run-time or compile-time. 8 * Run-time selection allows the application to select the desired behaviour, but code will be compiled for 9 * all options. Compile-time selection allows an optimizing compiler to remove all code specific to the 10 * disabled behaviour. 11 * 12 * The selectable behaviours are categorized as "standard features" that comply with the MXF specification, 13 * but implement it differently, and "non-standard features" that do not strictly comply with the MXF 14 * specification, yet may be useful in controlled application areas. 15 */ 16 /* 17 * Copyright (c) 2005, Matt Beard 18 * 19 * This software is provided 'as-is', without any express or implied warranty. 20 * In no event will the authors be held liable for any damages arising from 21 * the use of this software. 22 * 23 * Permission is granted to anyone to use this software for any purpose, 24 * including commercial applications, and to alter it and redistribute it 25 * freely, subject to the following restrictions: 26 * 27 * 1. The origin of this software must not be misrepresented; you must 28 * not claim that you wrote the original software. If you use this 29 * software in a product, an acknowledgment in the product 30 * documentation would be appreciated but is not required. 31 * 32 * 2. Altered source versions must be plainly marked as such, and must 33 * not be misrepresented as being the original software. 34 * 35 * 3. This notice may not be removed or altered from any source 36 * distribution. 37 */ 38 39 40 /************************/ 41 /* Comile-time settings */ 42 /************************/ 43 /* 44 * The following macros may be defined on the compiler command-line: 45 * 46 * MXFLIB_FEATURE_MASK - Only those features that match this mask are compiled 47 * Default setting is to allow all features 48 * 49 * MXFLIB_FEATURE_DEFAULT - The initial state of the feature bitmap 50 * Default setting is all features off 51 * 52 * MXFLIB_FEATURE_LOCK - Selects features that cannot be changed from their default state at run-time 53 * Default setting is all features unlocked 54 */ 55 56 #ifndef MXFLIB__FEATURES_H 57 #define MXFLIB__FEATURES_H 58 59 // Those features that may be enabled 60 #ifndef MXFLIB_FEATURE_MASK 61 #define MXFLIB_FEATURE_MASK (~UINT64_C(0)) 62 #endif 63 64 // Those features that are enabled by default 65 #ifndef MXFLIB_FEATURE_DEFAULT 66 #define MXFLIB_FEATURE_DEFAULT (UINT64_C(0)) 67 #endif 68 69 // Those features that cannot be changed at run-time 70 #ifndef MXFLIB_FEATURE_LOCK 71 #define MXFLIB_FEATURE_LOCK (UINT64_C(0)) 72 #endif 73 74 75 namespace mxflib 76 { 77 /* Standard library features (bits 0 to 30) */ 78 79 const UInt64 FeatureVersion1KLVFill = UINT64_C(1) << 0; //!< MXFLib feature: Write KLVFill items with the version 1 key 80 81 /* This sub-range is currently used by temporary fixes (bits 16 to 30) */ 82 83 const UInt64 FeatureNegPrechargeIndex = UINT64_C(1) << 16; //!< MXFLib feature: Use -ve indexing for precharge 84 85 // Reserve a bit for user-extensions 86 const UInt64 UserExtension = UINT64_C(1) << 31; //!< MXFLib feature: Reserved to allow user extensions 87 88 89 /* Non-Standard library functions - may cause non-complient behaviour (bits 32 to 63) */ 90 91 const UInt64 Feature32 = UINT64_C(1) << 32; 92 93 // Declare the features bitmap 94 extern UInt64 Features; 95 96 97 //! Set an MXFLib library feature (or multiple features) 98 /*! \return true if features set as requested 99 * \note If multiple features are requested and any one is unavailable none will be set 100 * 101 * DRAGONS: This code is written so that it will fold to: 102 * - a simple bit-set if the value of SetValue is known at compile-time and it is enabled and unlocked 103 * - an error message if the value of SetValue is known at compile-time and it is disabled or locked off 104 * - a simple bit-set if the value of SetValue is non known at compile time, but no features are disabled or locked off 105 * - the full function in all other cases 106 */ SetFeature(const UInt64 SetValue)107 inline bool SetFeature(const UInt64 SetValue) 108 { 109 // Fail if any of the features are disabled 110 if((SetValue & MXFLIB_FEATURE_MASK) != SetValue) 111 { 112 error("Feature 0x%s is not enabled in the current library\n", Int64toHexString(SetValue).c_str()); 113 return false; 114 } 115 116 // Fail if any of the features are locked (unless they are locked enabled!) 117 if(SetValue & MXFLIB_FEATURE_LOCK) 118 { 119 // Check if the locked bits are a problem (the locked value may be "on", which is fine) 120 UInt64 Locked = SetValue & MXFLIB_FEATURE_LOCK; 121 if(Locked & (~MXFLIB_FEATURE_DEFAULT)) 122 { 123 error("Feature 0x%s is locked off in the current library\n", Int64toHexString(SetValue).c_str()); 124 return false; 125 } 126 } 127 128 // Set the feature or features 129 Features |= SetValue; 130 131 // All OK 132 return true; 133 } 134 135 136 //! Clear an MXFLib library feature (or multiple features) 137 /*! \return true if features cleared as requested 138 * \note If clearing of multiple features is requested and any one is locked on none will be cleared 139 * 140 * DRAGONS: This code is written so that it will fold to: 141 * - a simple bit-clear if the value of SetValue is known at compile-time and it is unlocked 142 * - an error message if the value of SetValue is known at compile-time and it is locked on 143 * - a simple bit-clear if the value of SetValue is non known at compile time, but no features are locked on 144 * - the full function in all other cases 145 */ ClearFeature(const UInt64 ClearValue)146 inline bool ClearFeature(const UInt64 ClearValue) 147 { 148 // Fail if any of the features are locked (and they are locked enabled!) 149 if(ClearValue & MXFLIB_FEATURE_LOCK) 150 { 151 // Check if the locked bits are a problem (the locked value may be "off", which is fine) 152 UInt64 Locked = ClearValue & MXFLIB_FEATURE_LOCK; 153 if(Locked & MXFLIB_FEATURE_DEFAULT) 154 { 155 error("Feature 0x%s is locked on in the current library\n", Int64toHexString(ClearValue).c_str()); 156 return false; 157 } 158 } 159 160 // Clear the feature or features 161 Features &= ~ClearValue; 162 163 // All OK 164 return true; 165 } 166 167 168 //! Determine if an MXFLibrary feature is selected (or combination of features are all selected) 169 /* DRAGONS: This code is written so that it will fold to: 170 * - a compile-time result if the value of Value is known at compile-time and it is disabled or locked (on or off) 171 * - a simple bit-test if the value of SetValue is non known at compile time, but no features are disabled or locked 172 * - the full function in all other cases 173 */ Feature(const UInt64 Value)174 inline bool Feature(const UInt64 Value) 175 { 176 // If any of the features are disabled don't bother to read it 177 if((Value & MXFLIB_FEATURE_MASK) != Value) return false; 178 179 // If all of the features are locked simply return the compile-time setting 180 if(Value & MXFLIB_FEATURE_LOCK) 181 { 182 if((Value & MXFLIB_FEATURE_DEFAULT) == Value) return true; else return false; 183 } 184 185 // Run-time test 186 if((Value & Features) == Value) return true; else return false; 187 } 188 } 189 190 #endif // MXFLIB__FEATURES_H 191