Target Vibration API

Detailed Description

This set of functions controls the vibration of a tracker target. Currently only the zSpace stylus supports this capability. The vibration consists of alternating on and off periods. You can specify the length of the on and off periods, as well as how many times the vibration repeats. Alternatively, you can use predefined vibration patterns.

List of Functions

ZSError  zsSetTargetVibrationEnabled (ZSHandle targetHandle, ZSBool isVibrationEnabled)
ZSError  zsIsTargetVibrationEnabled (ZSHandle targetHandle, ZSBool* isVibrationEnabled)
ZSError  zsIsTargetVibrating (ZSHandle targetHandle, ZSBool* isVibrating)
ZSError  zsStartTargetVibration (ZSHandle targetHandle, ZSFloat onPeriod, ZSFloat offPeriod, ZSInt32 numTimes)
ZSError  zsStopTargetVibration (ZSHandle targetHandle)

Function Descriptions

ZSError zsIsTargetVibrating ( ZSHandle  targetHandle,
ZSBool*   isVibrating 
)

Checks whether a tracker target is currently vibrating.

Parameters:
[in] targetHandle A handle to the tracker target
[out] isVibrating True if vibrating, false otherwise
ZSError zsIsTargetVibrationEnabled ( ZSHandle  targetHandle,
ZSBool*   isVibrationEnabled 
)

Checks whether a tracker target's vibration is enabled.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] isVibrationEnabled True if enabled, false otherwise.
ZSError zsSetTargetVibrationEnabled ( ZSHandle  targetHandle,
ZSBool  isVibrationEnabled 
)

Sets whether a tracker target's vibration is enabled.

Remarks:
If vibration is disabled, any calls to zsStartVibration() will have no effect.
Parameters:
[in] targetHandle A handle to the tracker target.
[in] isVibrationEnabled True to enable the vibration, false otherwise.
Example:
 ZSContext context = ...;

 ZSHandle stylusHandle = NULL;
 zsFindTargetByType(context, ZS_TARGET_TYPE_PRIMARY, 0, &stylusHandle);
 zsSetTargetVibrationEnabled(stylusHandle, true);
ZSError zsStartTargetVibration ( ZSHandle  targetHandle,
ZSFloat  onPeriod,
ZSFloat  offPeriod,
ZSInt32  numTimes 
)

Starts the vibration for the specified on period, off period, and number of times.

Parameters:
[in] targetHandle A handle to the tracker target.
[in] onPeriod The duration in seconds of the vibration.
[in] offPeriod The duration in seconds between vibrations.
[in] numTimes The number of times the vibration occurs:
-1 -> Vibrate until zsStopTargetVibration() is called
0 -> Do nothing
N -> Vibrate N times
Example:
 ZSHandle stylusHandle;
 
 ZSFloat onPeriod    = 1.0f; // On period of 1 second
 ZSFloat offPeriod   = 2.0f; // Off period of 2 seconds
 ZSInt32 numTimes    = 2;    // Vibrate twice 

 // Start the vibration. 
 zsStartTargetVibration(stylusHandle, onPeriod, offPeriod, numTimes);
ZSError zsStopTargetVibration ( ZSHandle  targetHandle )

Interrupts the tracker target's vibration. This is meant to be called while a tracker target is in mid-vibration.

Parameters:
[in] targetHandle A handle to the tracker target.