2 ** =========================================================================
3 ** Copyright (c) 2003-2010 Immersion Corporation. All rights reserved.
4 ** Immersion Corporation Confidential and Proprietary
10 ** Constant and type definitions and macros for the Immersion
13 ** =========================================================================
15 #ifndef _IMMVIBECORE_H
16 #define _IMMVIBECORE_H
18 #include "ImmVibeOS.h"
30 /****************************************************************************
32 * Constants and Definitions
34 ****************************************************************************/
35 #define VIBE_MAX_MAGNITUDE 10000 /*!< Maximum Force Magnitude */
36 #define VIBE_MIN_MAGNITUDE 0 /*!< Minimum Force Magnitude */
37 #define VIBE_MAX_EFFECT_NAME_LENGTH 128 /*!< Maximum effect name length */
38 #define VIBE_INVALID_INDEX -1 /*!< Invalid Index */
40 /* DevicePropertyType */
41 #define VIBE_DEVPROPTYPE_LICENSE_KEY 0 /*!< Property type constant to set Application licence key */
42 #define VIBE_DEVPROPTYPE_PRIORITY 1 /*!< Property type constant to set device priority */
43 #define VIBE_DEVPROPTYPE_DISABLE_EFFECTS 2 /*!< Property type constant to enable/disable effects on a device */
44 #define VIBE_DEVPROPTYPE_STRENGTH 3 /*!< Property type constant to set the strength (volume) on a device */
45 #define VIBE_DEVPROPTYPE_MASTERSTRENGTH 4 /*!< Property type constant to set the strength (volume) on ALL devices */
47 /* Device type returned by ImmVibeGetDeviceCapabilityInt32 in 'xxxx' field of
48 'yyyy' struct for 'deviceCapabilityType' equal to
49 VIBE_DEVCAPTYPE_DEVICE_CATEGORY */
50 #define VIBE_DEVICECATEGORY_IFC 0 /*!< Device category constant for IFC Devices */
51 #define VIBE_DEVICECATEGORY_IMPULSE 1 /*!< Device category constant for Impulse Devices */
52 #define VIBE_DEVICECATEGORY_VIRTUAL 2 /*!< Device category constant for Virtual Devices */
53 #define VIBE_DEVICECATEGORY_EMBEDDED 3 /*!< Device category constant for Embedded Devices */
54 #define VIBE_DEVICECATEGORY_TETHERED 4 /*!< Device category constant for Tethered Devices */
55 #define VIBE_DEVICECATEGORY_IMMERSION_USB 5 /*!< Device category constant for Immersion USB Devices */
56 #define VIBE_DEVICECATEGORY_COMPOSITE 6 /*!< Device category constant for Composite Devices */
58 /* Effect type returned by ImmVibeGetIVTEffectType */
59 #define VIBE_EFFECT_TYPE_PERIODIC 0 /*!< Periodic Effect type constant */
60 #define VIBE_EFFECT_TYPE_MAGSWEEP 1 /*!< Magsweep Effect type constant */
61 #define VIBE_EFFECT_TYPE_TIMELINE 2 /*!< Timeline Effect type constant */
62 #define VIBE_EFFECT_TYPE_STREAMING 3 /*!< Streaming Effect type constant */
63 #define VIBE_EFFECT_TYPE_WAVEFORM 4 /*!< Waveform Effect type constant */
65 /* Device capability type passed as input 'deviceCapabilityType' argument to ImmVibeGetDeviceCapability... */
66 #define VIBE_DEVCAPTYPE_DEVICE_CATEGORY 0 /*!< Use ImmVibeGetDeviceCapabilityInt32 >*/
67 #define VIBE_DEVCAPTYPE_MAX_NESTED_REPEATS 1 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
68 #define VIBE_DEVCAPTYPE_NUM_ACTUATORS 2 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
69 #define VIBE_DEVCAPTYPE_ACTUATOR_TYPE 3 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
70 #define VIBE_DEVCAPTYPE_NUM_EFFECT_SLOTS 4 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
71 #define VIBE_DEVCAPTYPE_SUPPORTED_STYLES 5 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
72 /* VIBE_DEVCAPTYPE_SUPPORTED_CONTROL_MODES is deprecated and will not be an available constant
73 ** in future versions of this software. Please use VIBE_DEVCAPTYPE_SUPPORTED_STYLES instead. */
74 #define VIBE_DEVCAPTYPE_SUPPORTED_CONTROL_MODES VIBE_DEVCAPTYPE_SUPPORTED_STYLES
75 #define VIBE_DEVCAPTYPE_MIN_PERIOD 6 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
76 #define VIBE_DEVCAPTYPE_MAX_PERIOD 7 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
77 #define VIBE_DEVCAPTYPE_MAX_EFFECT_DURATION 8 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
78 #define VIBE_DEVCAPTYPE_SUPPORTED_EFFECTS 9 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
79 #define VIBE_DEVCAPTYPE_DEVICE_NAME 10 /*!< Use ImmVibeGetDeviceCapabilityString */
80 #define VIBE_DEVCAPTYPE_MAX_ENVELOPE_TIME 11 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
81 #define VIBE_DEVCAPTYPE_APIVERSIONNUMBER 12 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
82 #define VIBE_DEVCAPTYPE_MAX_IVT_SIZE_TETHERED 13 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
83 #define VIBE_DEVCAPTYPE_MAX_IVT_SIZE 14 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
84 #define VIBE_DEVCAPTYPE_EDITION_LEVEL 15 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
85 #define VIBE_DEVCAPTYPE_SUPPORTED_WAVE_TYPES 16 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
86 #define VIBE_DEVCAPTYPE_HANDSET_INDEX 17 /*!< Use ImmVibeGetDeviceCapabilityInt32 */
89 #define VIBE_INVALID_EFFECT_HANDLE_VALUE -1 /*!< Invalid Effect Handle */
90 #define VIBE_INVALID_DEVICE_HANDLE_VALUE -1 /*!< Invalid Device Handle */
92 /* Periodic, MagSweep effect Styles are only 4 bits and may be combined with other flags */
93 #define VIBE_STYLE_MASK 0x0F /*!< Style mask */
95 /* Periodic, MagSweep effect Styles */
96 #define VIBE_STYLE_SMOOTH 0 /*!< "Smooth" style */
97 #define VIBE_STYLE_STRONG 1 /*!< "Strong" style */
98 #define VIBE_STYLE_SHARP 2 /*!< "Sharp" style */
100 #define VIBE_DEFAULT_STYLE VIBE_STYLE_STRONG
102 /* VIBE_CONTROLMODE_ constants are deprecated and will not be available
103 ** in future versions of this software. Please use the VIBE_STYLE_ constants instead. */
104 #define VIBE_CONTROLMODE_SMOOTH VIBE_STYLE_SMOOTH
105 #define VIBE_CONTROLMODE_STRONG VIBE_STYLE_STRONG
106 #define VIBE_CONTROLMODE_SHARP VIBE_STYLE_SHARP
108 #define VIBE_DEFAULT_CONTROLMODE VIBE_DEFAULT_STYLE
110 /* Effect period resolution */
111 #define VIBE_PERIOD_RESOLUTION_MICROSECOND 0x80000000
113 /* Periodic effect Wave Types are only 4 bits and may be combined with other flags */
114 #define VIBE_WAVETYPE_SHIFT 4 /*!< Wave type shift */
115 #define VIBE_WAVETYPE_MASK 0xF0 /*!< Wave type mask */
117 /* Periodic effect Wave Types */
118 #define VIBE_WAVETYPE_SQUARE (1 << VIBE_WAVETYPE_SHIFT) /*!< "Square" wave type */
119 #define VIBE_WAVETYPE_TRIANGLE (2 << VIBE_WAVETYPE_SHIFT) /*!< "Triangle" wave type */
120 #define VIBE_WAVETYPE_SINE (3 << VIBE_WAVETYPE_SHIFT) /*!< "Sine" wave type */
121 #define VIBE_WAVETYPE_SAWTOOTHUP (4 << VIBE_WAVETYPE_SHIFT) /*!< "Sawtooth Up" wave type */
122 #define VIBE_WAVETYPE_SAWTOOTHDOWN (5 << VIBE_WAVETYPE_SHIFT) /*!< "Sawtooth Down" wave type */
124 #define VIBE_DEFAULT_WAVETYPE VIBE_WAVETYPE_SQUARE
126 /* String length constants */
127 #define VIBE_MAX_DEVICE_NAME_LENGTH 64 /*!<Maximum device name length */
128 #define VIBE_MAX_CAPABILITY_STRING_LENGTH 64 /*!<Maximum string length use by ImmVibeGetDeviceCapabilityString/ ImmVibeSetDeviceCapabilityString*/
129 #define VIBE_MAX_PROPERTY_STRING_LENGTH 64 /*!<Maximum string length use by ImmVibeGetDevicePropertyString/ ImmVibeSetDevicePropertyString */
131 /* Effect type support bit masks */
132 #define VIBE_PERIODIC_EFFECT_SUPPORT (1 << VIBE_EFFECT_TYPE_PERIODIC) /*!< Bitmask for Periodic effect support */
133 #define VIBE_MAGSWEEP_EFFECT_SUPPORT (1 << VIBE_EFFECT_TYPE_MAGSWEEP) /*!< Bitmask for Magsweep effect support */
134 #define VIBE_TIMELINE_EFFECT_SUPPORT (1 << VIBE_EFFECT_TYPE_TIMELINE) /*!< Bitmask for Timeline effect support*/
135 #define VIBE_STREAMING_EFFECT_SUPPORT (1 << VIBE_EFFECT_TYPE_STREAMING) /*!< Bitmask for Streaming effect support*/
136 #define VIBE_WAVEFORM_EFFECT_SUPPORT (1 << VIBE_EFFECT_TYPE_WAVEFORM) /*!< Bitmask for Waveform effect support */
138 /* Effect Style support bit masks */
139 #define VIBE_STYLE_SUPPORT_MASK 0x0000FFFF /*!< Effect style support mask */
140 #define VIBE_STYLE_SMOOTH_SUPPORT (1 << VIBE_STYLE_SMOOTH) /*!< Bitmask for "Smooth" style support */
141 #define VIBE_STYLE_STRONG_SUPPORT (1 << VIBE_STYLE_STRONG) /*!< Bitmask for "Strong" style support */
142 #define VIBE_STYLE_SHARP_SUPPORT (1 << VIBE_STYLE_SHARP) /*!< Bitmask for "Sharp" style support */
144 /* Wave type support bit masks */
145 /* Starts at 0x10000 to allow combining the flag with the supported style (nControlMode) 32 bits flag */
146 #define VIBE_WAVETYPE_SUPPORT_MASK 0xFFFF0000 /*!< Wave type support mask */
147 #define VIBE_WAVETYPE_SQUARE_SUPPORT (0x10000 << (VIBE_WAVETYPE_SQUARE >> VIBE_WAVETYPE_SHIFT)) /*!< Bitmask for "Square" wave type support */
148 #define VIBE_WAVETYPE_TRIANGLE_SUPPORT (0x10000 << (VIBE_WAVETYPE_TRIANGLE >> VIBE_WAVETYPE_SHIFT)) /*!< Bitmask for "Triangle" wave type support */
149 #define VIBE_WAVETYPE_SINE_SUPPORT (0x10000 << (VIBE_WAVETYPE_SINE >> VIBE_WAVETYPE_SHIFT)) /*!< Bitmask for "Sine" wave type support */
150 #define VIBE_WAVETYPE_SAWTOOTHUP_SUPPORT (0x10000 << (VIBE_WAVETYPE_SAWTOOTHUP >> VIBE_WAVETYPE_SHIFT)) /*!< Bitmask for "Saw tooth up" wave type support */
151 #define VIBE_WAVETYPE_SAWTOOTHDOWN_SUPPORT (0x10000 << (VIBE_WAVETYPE_SAWTOOTHDOWN >> VIBE_WAVETYPE_SHIFT)) /*!< Bitmask for "Saw tooth down" wave type support */
153 /* VIBE_CONTROLMODE_*_SUPPORT constants are deprecated and will not be available
154 ** in future versions of this software. Please use the VIBE_STYLE_*_SUPPORT constants instead. */
155 #define VIBE_CONTROLMODE_SMOOTH_SUPPORT VIBE_STYLE_SMOOTH_SUPPORT
156 #define VIBE_CONTROLMODE_STRONG_SUPPORT VIBE_STYLE_STRONG_SUPPORT
157 #define VIBE_CONTROLMODE_SHARP_SUPPORT VIBE_STYLE_SHARP_SUPPORT
159 /* Device State constants */
160 #define VIBE_DEVICESTATE_ATTACHED (1 << 0) /*!< Device is attached to the system */
161 #define VIBE_DEVICESTATE_BUSY (1 << 1) /*!< Device is busy (playing effects) */
163 /* Time in milliseconds */
164 #define VIBE_TIME_INFINITE VIBE_INT32_MAX /*!< Infinite time */
166 /* Effect priority */
167 #define VIBE_MIN_DEVICE_PRIORITY 0x0 /*!< Minimum Effect priority */
168 #define VIBE_MAX_DEV_DEVICE_PRIORITY 0x7 /*!< Maximum Effect priority for developers */
169 #define VIBE_MAX_OEM_DEVICE_PRIORITY 0xF /*!< Maximum Effect priority for OEMs */
170 #define VIBE_MAX_DEVICE_PRIORITY VIBE_MAX_OEM_DEVICE_PRIORITY /*!< FOR BACKWARD COMPATIBILITY ONLY;
171 new applications should use VIBE_MAX_DEV_DEVICE_PRIORITY
172 or VIBE_MAX_OEM_DEVICE_PRIORITY */
175 /* Device Actuator Type constants */
176 #define VIBE_DEVACTUATORTYPE_ERM 0
177 #define VIBE_DEVACTUATORTYPE_BLDC 1
178 #define VIBE_DEVACTUATORTYPE_LRA 2
179 #define VIBE_DEVACTUATORTYPE_PIEZO 4
180 #define VIBE_DEVACTUATORTYPE_PIEZO_WAVE 4
182 /* Device Default priority value */
183 #define VIBE_DEVPRIORITY_DEFAULT 0
186 #define VIBE_REPEAT_COUNT_INFINITE 255 /*!< Infinite repeat count */
188 /* Streaming Sample */
189 #define VIBE_MAX_STREAMING_SAMPLE_SIZE 255 /*!< Maximum size for streaming sample */
191 /* Effect state returned by ImmVibeGetEffectState */
192 #define VIBE_EFFECT_STATE_NOT_PLAYING 0 /*!< Not Playing and not paused */
193 #define VIBE_EFFECT_STATE_PLAYING 1 /*!< Playing */
194 #define VIBE_EFFECT_STATE_PAUSED 2 /*!< Paused */
197 #define VIBE_EDITION_3000 3000
198 #define VIBE_EDITION_4000 4000
199 #define VIBE_EDITION_5000 5000
201 /* Element type for IVTElement structure that is used by ImmVibeInsertIVTElement, ImmVibeReadIVTElement and ImmVibeRemoveIVTElement */
202 #define VIBE_ELEMTYPE_PERIODIC 0
203 #define VIBE_ELEMTYPE_MAGSWEEP 1
204 #define VIBE_ELEMTYPE_REPEAT 2
205 /* New in API v3.4 */
206 #define VIBE_ELEMTYPE_WAVEFORM 3
208 /* Composite device */
209 #define VIBE_MAX_LOGICAL_DEVICE_COUNT 16 /*!< Maximum number of device indices that can be passed to ImmVibeOpenCompositeDevice */
211 /****************************************************************************
215 ****************************************************************************/
216 #define VIBE_SUCCEEDED(n) ((n) >= 0)
217 #define VIBE_FAILED(n) ((n) < 0)
218 #define VIBE_IS_INVALID_DEVICE_HANDLE(n) (((n) == 0) || ((n) == VIBE_INVALID_DEVICE_HANDLE_VALUE))
219 #define VIBE_IS_INVALID_EFFECT_HANDLE(n) (((n) == 0) || ((n) == VIBE_INVALID_EFFECT_HANDLE_VALUE))
220 #define VIBE_IS_VALID_DEVICE_HANDLE(n) (((n) != 0) && ((n) != VIBE_INVALID_DEVICE_HANDLE_VALUE))
221 #define VIBE_IS_VALID_EFFECT_HANDLE(n) (((n) != 0) && ((n) != VIBE_INVALID_EFFECT_HANDLE_VALUE))
223 /****************************************************************************
225 * Error and Return value codes.
227 ****************************************************************************/
228 #define VIBE_S_SUCCESS 0 /*!< Success */
229 #define VIBE_S_FALSE 0 /*!< False */
230 #define VIBE_S_TRUE 1 /*!< True */
231 #define VIBE_W_NOT_PLAYING 1 /*!< Effect is not playing */
232 #define VIBE_W_INSUFFICIENT_PRIORITY 2 /*!< Effect doesn't have enough priority to play: higher priority effect is playing on the device */
233 #define VIBE_W_EFFECTS_DISABLED 3 /*!< Effects are disabled on the device */
234 #define VIBE_W_NOT_PAUSED 4 /*!< The ImmVibeResumePausedEffect function cannot resume an effect that is not paused */
235 #define VIBE_E_ALREADY_INITIALIZED -1 /*!< The API is already initialized (NOT USED) */
236 #define VIBE_E_NOT_INITIALIZED -2 /*!< The API is already is not initialized */
237 #define VIBE_E_INVALID_ARGUMENT -3 /*!< Invalid argument was used in a API function call */
238 #define VIBE_E_FAIL -4 /*!< Generic error */
239 #define VIBE_E_INCOMPATIBLE_EFFECT_TYPE -5 /*!< Incompatible Effect type has been passed into API function call */
240 #define VIBE_E_INCOMPATIBLE_CAPABILITY_TYPE -6 /*!< Incompatible Capability type was used into one of the following functions */
241 #define VIBE_E_INCOMPATIBLE_PROPERTY_TYPE -7 /*!< Incompatible Property type was used into one of the following functions */
242 #define VIBE_E_DEVICE_NEEDS_LICENSE -8 /*!< Access to the instance of the device is locked until a valid license key is provided. */
243 #define VIBE_E_NOT_ENOUGH_MEMORY -9 /*!< The API function cannot allocate memory to complete the process */
244 #define VIBE_E_SERVICE_NOT_RUNNING -10 /*!< ImmVibeService is not running */
245 #define VIBE_E_INSUFFICIENT_PRIORITY -11 /*!< Not enough priority to achieve the request (insufficient license key priority) */
246 #define VIBE_E_SERVICE_BUSY -12 /*!< ImmVibeService is busy and failed to complete the request */
247 #define VIBE_E_NOT_SUPPORTED -13 /*!< The API function is not supported by this version of the API */
249 /****************************************************************************
253 ****************************************************************************/
254 typedef VibeInt32 VibeStatus;
256 /****************************************************************************
260 ****************************************************************************/
263 VibeInt32 m_nDuration;
264 VibeInt32 m_nMagnitude;
267 VibeInt32 m_nAttackTime;
268 VibeInt32 m_nAttackLevel;
269 VibeInt32 m_nFadeTime;
270 VibeInt32 m_nFadeLevel;
275 VibeInt32 m_nDuration;
276 VibeInt32 m_nMagnitude;
279 VibeInt32 m_nAttackTime;
280 VibeInt32 m_nAttackLevel;
281 VibeInt32 m_nFadeTime;
282 VibeInt32 m_nFadeLevel;
284 VibeInt32 m_nActuatorIndex;
289 VibeInt32 m_nDuration;
290 VibeInt32 m_nMagnitude;
292 VibeInt32 m_nAttackTime;
293 VibeInt32 m_nAttackLevel;
294 VibeInt32 m_nFadeTime;
295 VibeInt32 m_nFadeLevel;
300 VibeInt32 m_nDuration;
301 VibeInt32 m_nMagnitude;
303 VibeInt32 m_nAttackTime;
304 VibeInt32 m_nAttackLevel;
305 VibeInt32 m_nFadeTime;
306 VibeInt32 m_nFadeLevel;
308 VibeInt32 m_nActuatorIndex;
314 VibeInt32 m_nDuration;
320 const VibeUInt8 * m_pData;
321 VibeInt32 m_nDataSize;
322 VibeInt32 m_nSamplingRate;
323 VibeInt32 m_nBitDepth;
324 VibeInt32 m_nMagnitude;
325 VibeInt32 m_nActuatorIndex;
330 VibeInt32 m_nElementType;
334 VibeIVTPeriodic m_periodic;
335 VibeIVTMagSweep m_magsweep;
336 VibeIVTRepeat m_repeat;
342 VibeInt32 m_nElementType;
346 VibeIVTPeriodic2 m_periodic;
347 VibeIVTMagSweep2 m_magsweep;
348 VibeIVTRepeat m_repeat;
354 VibeInt32 m_nElementType;
358 VibeIVTPeriodic2 m_periodic;
359 VibeIVTMagSweep2 m_magsweep;
360 VibeIVTRepeat m_repeat;
362 VibeIVTWaveform m_waveform;
366 #endif /* IMMVIBECORE_H */