/src/ois/includes/OISEffect.h

  1/*
  2The zlib/libpng License
  3
  4Copyright (c) 2005-2007 Phillip Castaneda (pjcast -- www.wreckedgames.com)
  5
  6This software is provided 'as-is', without any express or implied warranty. In no event will
  7the authors be held liable for any damages arising from the use of this software.
  8
  9Permission is granted to anyone to use this software for any purpose, including commercial
 10applications, and to alter it and redistribute it freely, subject to the following
 11restrictions:
 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
 28namespace 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