Open topic with navigation

# 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.

Open topic with navigation