1 /* 2 The zlib/libpng License 3 4 Copyright (c) 2005-2007 Phillip Castaneda (pjcast -- www.wreckedgames.com) 5 6 This software is provided 'as-is', without any express or implied warranty. In no event will 7 the authors be held liable for any damages arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, including commercial 10 applications, and to alter it and redistribute it freely, subject to the following 11 restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not claim that 14 you wrote the original software. If you use this software in a product, 15 an acknowledgment in the product documentation would be appreciated but is 16 not required. 17 18 2. Altered source versions must be plainly marked as such, and must not be 19 misrepresented as being the original software. 20 21 3. This notice may not be removed or altered from any source distribution. 22 */ 23 #ifndef OIS_Effect_H 24 #define OIS_Effect_H 25 26 #include "OISPrereqs.h" 27 28 namespace OIS 29 { 30 //Predeclare some Effect Property structs 31 class ForceEffect; 32 class ConstantEffect; 33 class RampEffect; 34 class PeriodicEffect; 35 class ConditionalEffect; 36 37 /** 38 Force Feedback is a relatively complex set of properties to upload to a device. 39 The best place for information on the different properties, effects, etc is in 40 the DX Documentation and MSDN - there are even pretty graphs ther =) 41 As this class is modeled on the the DX interface you can apply that same 42 knowledge to creating effects via this class on any OS supported by OIS. 43 44 In anycase, this is the main class you will be using. There is *absolutely* no 45 need to instance any of the supporting ForceEffect classes yourself. 46 */ 47 class _OISExport Effect 48 { 49 /** 50 hidden so this class cannot be instanced with default constructor 51 */ 52 Effect(); 53 public: 54 //! Type of force 55 enum EForce 56 { 57 UnknownForce = 0, 58 ConstantForce, 59 RampForce, 60 PeriodicForce, 61 ConditionalForce, 62 CustomForce, 63 _ForcesNumber // Always keep in last position. 64 }; 65 66 static const char* getForceTypeName(EForce eValue); 67 68 //! Type of effect 69 enum EType 70 { 71 //Type ----- Pairs with force: 72 Unknown = 0, //UnknownForce 73 Constant, //ConstantForce 74 Ramp, //RampForce 75 Square, //PeriodicForce 76 Triangle, //PeriodicForce 77 Sine, //PeriodicForce 78 SawToothUp, //PeriodicForce 79 SawToothDown,//PeriodicForce 80 Friction, //ConditionalForce 81 Damper, //ConditionalForce 82 Inertia, //ConditionalForce 83 Spring, //ConditionalForce 84 Custom, //CustomForce 85 _TypesNumber // Always keep in last position. 86 }; 87 88 static const char* getEffectTypeName(EType eValue); 89 90 //! Direction of the Force 91 enum EDirection 92 { 93 NorthWest, 94 North, 95 NorthEast, 96 East, 97 SouthEast, 98 South, 99 SouthWest, 100 West, 101 _DirectionsNumber // Always keep in last position. 102 }; 103 104 static const char* getDirectionName(EDirection eValue); 105 106 /** 107 This constructor allows you to set the force type and effect. 108 */ 109 Effect(EForce ef, EType et); 110 virtual ~Effect(); 111 112 const EForce force; 113 const EType type; 114 115 //Infinite Time 116 static const unsigned int OIS_INFINITE = 0xFFFFFFFF; 117 118 //-------------------------------------------------------------------// 119 //--- Set these variables before uploading or modifying an effect ---// 120 121 //Direction to apply to the force - affects two axes+ effects 122 EDirection direction; 123 124 //Number of button triggering an effect (-1 means no trigger) 125 short trigger_button; 126 127 //Time to wait before an effect can be re-triggered (microseconds) 128 unsigned int trigger_interval; 129 130 //Duration of an effect (microseconds) 131 unsigned int replay_length; 132 133 //Time to wait before to start playing an effect (microseconds) 134 unsigned int replay_delay; 135 136 //Get the specific Force Effect. This should be cast depending on the EForce 137 ForceEffect* getForceEffect() const; 138 139 /** 140 @remarks 141 Set the number of Axes to use before the initial creation of the effect. 142 Can only be done prior to creation! Use the FF interface to determine 143 how many axes can be used (are availiable) 144 */ 145 void setNumAxes(short nAxes); 146 147 /** 148 @remarks 149 Returns the number of axes used in this effect 150 */ 151 short getNumAxes() const; 152 153 //------------- Library Internal -------------------------------------// 154 /** 155 set internally.. do not change or you will not be able to upload/stop 156 this effect any more. It will become lost. It is mutable so even 157 with const reference it can/will be changed by this lib 158 */ 159 mutable int _handle; 160 protected: 161 ForceEffect* effect; //Properties depend on EForce 162 short axes; //Number of axes to use in effect 163 }; 164 165 //-----------------------------------------------------------------------------// 166 /** 167 Base class of all effect property classes 168 */ 169 class _OISExport ForceEffect 170 { 171 public: 172 virtual ~ForceEffect() {} 173 }; 174 175 //-----------------------------------------------------------------------------// 176 /** 177 An optional envelope to be applied to the start/end of an effect. If any of 178 these values are nonzero, then the envelope will be used in setting up the 179 effect. 180 */ 181 class _OISExport Envelope : public ForceEffect 182 { 183 public: 184 Envelope() : attackLength(0), attackLevel(0), fadeLength(0), fadeLevel(0) {} 185 #if defined(OIS_MSVC_COMPILER) 186 #pragma warning (push) 187 #pragma warning (disable : 4800) 188 #endif 189 bool isUsed() const { return attackLength | attackLevel | fadeLength | fadeLevel; } 190 #if defined(OIS_MSVC_COMPILER) 191 #pragma warning (pop) 192 #endif 193 194 // Duration of the attack (microseconds) 195 unsigned int attackLength; 196 197 // Absolute level at the beginning of the attack (0 to 10K) 198 // (automatically signed when necessary by FF core according to effect level sign) 199 unsigned short attackLevel; 200 201 // Duration of fade (microseconds) 202 unsigned int fadeLength; 203 204 // Absolute level at the end of fade (0 to 10K) 205 // (automatically signed when necessary by FF core according to effect level sign) 206 unsigned short fadeLevel; 207 }; 208 209 //-----------------------------------------------------------------------------// 210 /** 211 Use this class when dealing with Force type of Constant 212 */ 213 class _OISExport ConstantEffect : public ForceEffect 214 { 215 public: 216 ConstantEffect() : level(5000) {} 217 218 class Envelope envelope; //Optional envolope 219 signed short level; //-10K to +10k 220 }; 221 222 //-----------------------------------------------------------------------------// 223 /** 224 Use this class when dealing with Force type of Ramp 225 */ 226 class _OISExport RampEffect : public ForceEffect 227 { 228 public: 229 RampEffect() : startLevel(0), endLevel(0) {} 230 231 class Envelope envelope; //Optional envelope 232 signed short startLevel; //-10K to +10k 233 signed short endLevel; //-10K to +10k 234 }; 235 236 //-----------------------------------------------------------------------------// 237 /** 238 Use this class when dealing with Force type of Periodic 239 */ 240 class _OISExport PeriodicEffect : public ForceEffect 241 { 242 public: 243 PeriodicEffect() : magnitude(0), offset(0), phase(0), period(0) {} 244 245 class Envelope envelope; //Optional Envelope 246 247 unsigned short magnitude; //0 to 10,0000 248 signed short offset; 249 unsigned short phase; //Position at which playback begins 0 to 35,999 250 unsigned int period; //Period of effect (microseconds) 251 }; 252 253 //-----------------------------------------------------------------------------// 254 /** 255 Use this class when dealing with Force type of Condional 256 */ 257 class _OISExport ConditionalEffect : public ForceEffect 258 { 259 public: 260 ConditionalEffect() : 261 rightCoeff(0), leftCoeff(0), rightSaturation(0), leftSaturation(0), 262 deadband(0), center(0) {} 263 264 signed short rightCoeff; //-10k to +10k (Positive Coeff) 265 signed short leftCoeff; //-10k to +10k (Negative Coeff) 266 267 unsigned short rightSaturation; //0 to 10k (Pos Saturation) 268 unsigned short leftSaturation; //0 to 10k (Neg Saturation) 269 270 //Region around center in which the condition is not active, in the range 271 //from 0 through 10,000 272 unsigned short deadband; 273 274 //(Offset in DX) -10k and 10k 275 signed short center; 276 }; 277 } 278 #endif //OIS_Effect_H 279
