Develop

API tutorial: #1 Amplitude Modulation example code

1180 views 28/07/2018 Nicci 5

How Amplitude Modulation works

To feel a control point it must vary. With Amplitude Modulation, the intensity of the control point changes. The Amplitude Modulation emitter handle this modulation for you. You tell the Ultrahaptics SDK where to place the points.

When you wish to change to control point you send an update. Updates consist of control point position, intensity and frequency. The Ultrahaptics hardware handles the modulation for each control point.

Default control point modulation frequency is 125 Hz. All control points use the same frequency when using more than one.
 
Tip: Experiment with frequencies around 100 to 300 Hz to find the best sensation for your application.
 
Intensity is an arbitrary scale and ranges from 0 to maximum 1.

Note: Control Point intensity is not a linear control for perceived output strength. Use a non-linear mapping when converting perceived output strength to intensity.

Amplitude Modulation walkthrough

To use the Amplitude Modulation API, follow these steps:

  1. Create an instance of Ultrahaptics::AmplitudeModulation::Emitter.
  2. Call the emitter’s update() method with one or more control points to begin emitting haptic feedback.
  3. When you want to stop outputting from the array, there are three options:

(a) call the emitter’s stop() method,

(b) call the emitter’s update() method with an empty array of control points, or

(c) set the intensity of the control points to 0.

You can change the default frequency from 125 Hz by using the Control Point’s setFrequency() method, or in the ControlPoint constructor.

A closer look at AmplitudeModulation_Focus.cpp

The Ultrahaptics SDK comes with a selection of C++ and C# examples. Read our tutorial on building the examples.

Here we look at the AmplitudeModulation_Focus example. A single Control Point, with a modulation frequency of 200 Hz and maximum intensity, is positioned 20 cm above the centre of the array. Once updated, the Control Point will continue emitting until a key is pressed. The emitter’s destructor will stop the output.

#include <cstdlib>
#include <iostream>
#include <string>

#include <UltrahapticsAmplitudeModulation.hpp>

int main(int argc, char *argv[])
{
    // Create an emitter.
    Ultrahaptics::AmplitudeModulation::Emitter emitter;

    // Set frequency to 200 Hertz and maximum intensity
    float frequency = 200.0 * Ultrahaptics::Units::hertz;
    float intensity = 1.0f;

    // Position the focal point at 20 centimeters above the array.
    float distance = 20.0 * Ultrahaptics::Units::centimetres;

    // Optionally, specify the focal point distance in cm on the command line
    if (argc > 1)
    {
        distance = atof(argv[1]) * Ultrahaptics::Units::centimetres;
    }

    Ultrahaptics::Vector3 position1(0.0f, 0.0f, distance);
    Ultrahaptics::AmplitudeModulation::ControlPoint point1(position1, intensity, frequency);

    // Emit the point.
    if (!emitter.update(point1))
    {
        std::cout << "Couldn't start emitter." << std::endl;
        return 1;
    }

    // Display the message.
    std::cout << "Hit ENTER to quit...";
    // Wait for enter key to be pressed.
    std::string line;
    std::getline(std::cin, line);

    // Emitter shuts down on exit.
    return 0;
}

Was this helpful?