Meta Developers

On the Meta Quest Touch Pro controller, there are three elements that can play haptics: one VCM (Voice Coil Motor) and two LRAs (Linear Resonant Actuators) for the thumb and trigger.

LRAs vibrate at a set frequency, which means the only thing you can modulate is amplitude. VCMs, on the other hand, can vibrate at a much wider range of frequencies, that is 50Hz to 500Hz. This allows for a more immersive experience as you will be able to distinguish between the low rumbling of thunder and the high-pitched blaring of an alarm.

In addition to simple haptics, there are two OpenXR extensions that enable you to trigger haptics on varying levels of granularity: PCM (Pulse Code Modulation) and Amplitude Envelope. The LRAs can be triggered using the existing simple haptic only.

PCM Haptics

Using this extension, you can specify a high fidelity haptic effect by modulating both the amplitude and the frequency. To do so, you must pass the following XrHapticPcmVibrationFB struct in function xrApplyHapticFeedback:

typedef struct XrHapticPcmVibrationFB {
    XrStructureType type;
    const void* XR_MAY_ALIAS next;
    uint32_t bufferSize;
    const float* buffer;
    float sampleRate;
    XrBool32 append;
    uint32_t* samplesConsumed;
} XrHapticPcmVibrationFB;

The description of the struct fields is the following:

Field	Description
`buffer`	a float array that represents the haptic feedback samples. If you consider the haptic effect as a sampled analog audio, then this buffer will contain the samples representing that effect. The values in this buffer are expected to be in the range [-1.0, 1.0].
`next`	next is NULL or a pointer to the next structure in a structure chain. For more details, read Passing Function Parameters through Structs.
`bufferSize`	number of elements in `buffer`
`sampleRate`	a float value representing the number of samples to be played from `buffer` per second. This is used to determine the duration of the effect. Based on this sample rate, the runtime resamples the buffer to match the device’s sample rate.
`append`	to support long haptic effects, set this flag to `true`, which means that the effect will be played after the currently-playing effect is finished. If `append` is `false`, then the provided effect will begin playing immediately.
`samplesConsumed`	this value will be populated to tell the application about how many samples were consumed from the `buffer` you have provided. This helps you estimate when you can make the next API call and whether to resend the samples which were not consumed from the previous API call.

To call haptics you must use the xrApplyHapticFeedback function by passing this new struct as a function parameter. Here is an example on how to create a XrHapticPcmVibrationFB struct and pass it to xrApplyHapticFeedback:

XrHapticPcmVibrationFB v{XR_TYPE_HAPTIC_PCM_VIBRATION_FB, nullptr};
v.sampleRate = sampleRate;
v.bufferSize = bufferSize;
v.buffer = pcmBuffer.data();
uint32_t samplesUsed = 0;
v.samplesConsumed = &samplesUsed;
v.append = XR_FALSE;
XrHapticActionInfo hai = {XR_TYPE_HAPTIC_ACTION_INFO, nullptr};
hai.action = action;
hai.subactionPath = subactionPath;
OXR(xrApplyHapticFeedback(Session, &hai, (const XrHapticBaseHeader*)&v));
samplesUsed = *(v.samplesConsumed);

For example, if you want to play a haptic effect of constant amplitude for one second, create the struct as follows:

XrHapticPcmVibrationFB v{XR_TYPE_HAPTIC_PCM_VIBRATION_FB, nullptr};
float buffer[] = {1};
v.sampleRate = 1;
v.bufferSize = 1;
v.buffer = buffer.data();
uint32_t samplesUsed = 0;
v.samplesConsumed = &samplesUsed;
v.append = XR_FALSE;

In addition to the above struct, you can use the xrGetDeviceSampleRateFB function. This function returns the haptic sample rate on the last connected controller. If the controller does not support PCM haptics, the function will return 0. The returned value will change if the connected controller changes, so call this function whenever necessary to ensure your application has the latest information on the device sample rate.

The xrGetDeviceSampleRateFB definition is as follows:

XRAPI_ATTR XrResult XRAPI_CALL xrGetDeviceSampleRateFB(
    XrSession session,
    const XrHapticActionInfo* hapticActionInfo,
    XrDevicePcmSampleRateGetInfoFB* deviceSampleRate);

When you call this function, the runtime populates a deviceSampleRate struct, which is defined as follows:

typedef struct XrDevicePcmSampleRateGetInfoFB {
    XrStructureType type;
    const void* XR_MAY_ALIAS next;
    float sampleRate;
} XrDevicePcmSampleRateGetInfoFB;

Here is an example on how to use the xrGetDeviceSampleRateFB:

PFN_xrGetDeviceSampleRateFB xrGetDeviceSampleRateFB = nullptr;
OXR(xrGetInstanceProcAddr(
    GetInstance(),
    "xrGetDeviceSampleRateFB",
    (PFN_xrVoidFunction*)(&xrGetDeviceSampleRateFB)));
OXR(xrGetDeviceSampleRateFB(Session, &hai, &leftDeviceSampleRate_));
cout << leftDeviceSampleRate_.sampleRate;

If the sampleRate you provide in xrHapticPcmVibrationFB is different from the value returned by xrGetDeviceSampleRateFB, then the runtime will resample the buffer.

Meta Quest Touch Support for PCM

PCM haptics is also supported on Meta Quest Touch Controller. When PCM haptics is triggered on the Touch Controller, the runtime resamples the data in buffer, and plays an equivalent haptic effect on the controller. If you do not want the runtime to perform any resampling, it is recommended that you use the sampleRate returned by xrGetDeviceSampleRateFB function and generate the haptics data based on this sampleRate. PCM haptics is also supported on Meta Quest Touch Controller. When PCM haptics is triggered on the Touch Controller, the runtime resamples the data in buffer, and plays an equivalent haptic effect on the controller. If you do not want the runtime to perform any resampling, then it is recommended that you use the sampleRate returned by xrGetDeviceSampleRateFB function and generate the haptics data based on this sampleRate.

Amplitude Envelope

Consider the following complex analog signal.

The amplitude envelope of a signal is a smooth curve outlining its extremes. Amplitude envelope for the above signal would look like this:

Using this extension, you can specify a haptic effect by modulating only the amplitude and not the frequency. Unlike PCM, you can create a struct that enables you to specify a low fidelity haptic effect. However, this struct is easier to author than PCM. To specify this effect you must pass the XrHapticAmplitudeEnvelopeVibrationFB struct to the xrApplyHapticFeedback function. The struct definition is the following:

typedef struct XrHapticAmplitudeEnvelopeVibrationFB {
    XrStructureType type;
    const void* XR_MAY_ALIAS next;
    XrDuration duration;
    uint32_t amplitudeCount;
    const float* amplitudes;
} XrHapticAmplitudeEnvelopeVibrationFB;

Field	Description
`next`	next is NULL or a pointer to the next structure in a structure chain. For more details, read Passing Function Parameters through Structs.
`duration`	an XrDuration that represents the duration in nanoseconds for which the effect will be played.
`amplitudeCount`	number of elements in the array
`amplitudes`	array representing the amplitude envelope values

To call haptics, you must use the xrApplyHapticFeedback function by passing this new struct as a function parameter. Here is an example on how to create the struct and pass to xrApplyHapticFeedback:

XrHapticAmplitudeEnvelopeVibrationFB v{
    XR_TYPE_HAPTIC_AMPLITUDE_ENVELOPE_VIBRATION_FB, nullptr};
v.duration = durationNanoSecs;
v.amplitudeCount = (uint32_t)envelopeSize;
v.amplitudes = amplitudes.data();
XrHapticActionInfo hai = {XR_TYPE_HAPTIC_ACTION_INFO, nullptr};
hai.action = action;
hai.subactionPath = subactionPath;
OXR(xrApplyHapticFeedback(Session, &hai, (const XrHapticBaseHeader*)&v));

Meta Quest Touch Support for Amplitude Envelope

Amplitude Envelope is supported on Meta Quest Touch Controller. When Amplitude Envelope is triggered on Touch Controller, the runtime will resample the data in amplitudes based on the duration and amplitudeCount, along with the device sample rate.

Localized Haptics

As mentioned above, on Meta Quest Touch Pro Controller, there are three elements which can play haptics: one VCM (Voice Coil Motor), and two LRA (Linear Resonant Actuator) for thumb and trigger. LRAs vibrate at a set frequency, which means the only thing you can modulate is amplitude. In comparison, the Meta Quest Touch Controller has only one haptic element. While the VCM can be triggered using PCM, Amplitude Envelope, or simple haptics, the LRAs can be triggered using simple haptics only.

Here is an example on how to trigger haptics on left thumb for one second:

// Create a thumb action
ThumbHapticAction = CreateAction(
            BaseActionSet,
            XR_ACTION_TYPE_VIBRATION_OUTPUT,
            "the_thumb_haptic",
            nullptr,
            2,
            handSubactionPaths);

XrHapticVibration v{XR_TYPE_HAPTIC_VIBRATION, nullptr};
        v.amplitude = 1;
        v.duration = ToXrTime(1); //1s
        XrHapticActionInfo hai = {XR_TYPE_HAPTIC_ACTION_INFO, nullptr};
        hai.action = ThumbHapticAction;
        hai.subactionPath = LeftHandPath;
        OXR(xrApplyHapticFeedback(Session, &hai, (const XrHapticBaseHeader*)&v));

Known Issues

There is a known limitation in the current release: If haptics is triggered on the thumb LRA and on both the controllers using XR_PATH_NULL in subactionPath of XrHapticActionInfo, then haptics are played for double the time on the right controller’s thumb LRA. To mitigate this, the application will have to call xrStopHapticFeedback on the right controller.

Did you find this page helpful?