XrHapticParametricVibrationEXT(3)

C Specification

The XrHapticParametricVibrationEXT structure is defined as:

// Provided by XR_EXT_haptic_parametric
typedef struct XrHapticParametricVibrationEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 amplitudePointCount;
    const XrHapticParametricPointEXT*        amplitudePoints;
    uint32_t                                 frequencyPointCount;
    const XrHapticParametricPointEXT*        frequencyPoints;
    uint32_t                                 transientCount;
    const XrHapticParametricTransientEXT*    transients;
    float                                    minFrequencyHz;
    float                                    maxFrequencyHz;
    XrHapticParametricStreamFrameTypeEXT     streamFrameType;
} XrHapticParametricVibrationEXT;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
amplitudePointCount is the number of points in amplitudePoints.
amplitudePoints is an array of XrHapticParametricPointEXT, describing how the intensity of the vibration changes over time.
frequencyPointCount is the number of points in frequencyPoints.
frequencyPoints is an array of XrHapticParametricPointEXT, describing how the frequency of the vibration changes over time. If it is NULL, a vibration frequency of 0.5 is used for the entire haptic event.
transientCount is the number of transients in transients.
transients is an array of XrHapticParametricTransientEXT, describing the transients in the haptic event. If it is NULL, the haptic event has no transients.
minFrequencyHz is the absolute frequency, in Hertz, that the normalized frequency of 0.0 maps to. If it is XR_FREQUENCY_UNSPECIFIED, the runtime maps 0.0 to the lowest frequency supported by the haptic element.
maxFrequencyHz is the absolute frequency, in Hertz, that the normalized frequency of 1.0 maps to. If it is XR_FREQUENCY_UNSPECIFIED, the runtime maps 1.0 to the highest frequency supported by the haptic element.
streamFrameType is the XrHapticParametricStreamFrameTypeEXT that describes if and how the data in this structure is part of a longer haptic stream.

Description

This structure describes a parametric haptic event.

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrApplyHapticFeedback if any of the following conditions are not met:

When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_NONE_EXT or XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_FIRST_FRAME_EXT, the structure must contain at least two amplitude points. For all other values of streamFrameType, the structure must contain at least one amplitude point.
The structure must not contain more than XR_HAPTIC_PARAMETRIC_MAX_POINTS_TRANSIENTS_EXT amplitude points, frequency points or transients, respectively. An application can trigger haptic events with more than XR_HAPTIC_PARAMETRIC_MAX_POINTS_TRANSIENTS_EXT amplitude points, frequency points or transients by calling xrApplyHapticFeedback multiple times in a sequence, see https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#ext_haptic_parametric-streaming for details.
When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_NONE_EXT or XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_FIRST_FRAME_EXT, the first amplitude and frequency point must be at time 0.
When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_FIRST_FRAME_EXT, the time of the last amplitude point in the frame must be greater than or equal to XrHapticParametricPropertiesEXT::minimumFirstFrameDuration.
The time of the last frequency point and the last transient of the stream must be less than or equal to the time of the last amplitude point of the stream.
When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_INTERMEDIATE_FRAME_EXT or XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_LAST_FRAME_EXT, a stream must already be running on the haptic element.
minFrequencyHz and maxFrequencyHz must either be both XR_FREQUENCY_UNSPECIFIED, or both specified in the range XR_HAPTIC_PARAMETRIC_FREQUENCY_MIN_HZ_EXT - XR_HAPTIC_PARAMETRIC_FREQUENCY_MAX_HZ_EXT (inclusive).
maxFrequencyHz must be equal to or larger than minFrequencyHz, or XR_FREQUENCY_UNSPECIFIED.
When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_INTERMEDIATE_FRAME_EXT or XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_LAST_FRAME_EXT, minFrequencyHz and maxFrequencyHz must both be XR_FREQUENCY_UNSPECIFIED. The application may only set the absolute frequency range in the first https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#ext_haptic_parametric-haptic-frame, and the runtime uses the range for the entire haptic event.
Each amplitude point and frequency point must not have an earlier time than the one preceding it.
Each transient must have a later time than the one preceding it.
The amplitude and frequency of a point or transient must be between 0.0 and 1.0 (inclusive).

In addition to the restrictions above, the following is explicitly allowed:

The first transient may be at any time, it does not need to be at time 0.
The number of amplitude points, frequency points and transients may be completely independent of each other.
Amplitude points, frequency points and transients with the same array index may be at a different times.
There may be multiple amplitude points or frequency points at the same time. Applications can use this to model an abrupt jump in amplitude or frequency. The order of the points in the array determines the starting and ending values of the jump.

If the time of the last frequency point of the stream is earlier than the time of the last amplitude point of the stream, the runtime must continue and finish the haptic event with the frequency of the last frequency point. As per the validation rules, the opposite case, a stream in which the time of the last amplitude point of the stream is earlier than the time of the last frequency point of the stream, is not allowed, and the runtime must return XR_ERROR_VALIDATION_FAILURE from xrApplyHapticFeedback.

The application may call xrHapticParametricGetPropertiesEXT to determine the frequency range supported by the haptic element. If the range specified by minFrequencyHz and maxFrequencyHz is outside of the supported range, the runtime must clamp the values to the supported range. The runtime then maps the normalized frequency range to the clamped absolute frequency range.

When streamFrameType is XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_NONE_EXT or XR_HAPTIC_PARAMETRIC_STREAM_FRAME_TYPE_FIRST_FRAME_EXT, a new haptic event is started. In this case, the runtime must cancel any unfinished haptic events currently running on the haptic element, as usual for the core specification. This applies to all types of haptic events, including e.g. XrHapticPcmVibrationFB, XrHapticVibration and XrHapticParametricVibrationEXT.

When the call to xrApplyHapticFeedback fails with an error code, the runtime must ignore the new frame and discard the haptic data contained in it. The runtime must not cancel or otherwise modify an existing stream, if any, currently running on the haptic element. The runtime must not start a new haptic event.

Valid Usage (Implicit)

The XR_EXT_haptic_parametric extension must be enabled prior to using XrHapticParametricVibrationEXT
type must be XR_TYPE_HAPTIC_PARAMETRIC_VIBRATION_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
amplitudePoints must be a pointer to an array of amplitudePointCount valid XrHapticParametricPointEXT structures
If frequencyPointCount is not 0, frequencyPoints must be a pointer to an array of frequencyPointCount valid XrHapticParametricPointEXT structures
If transientCount is not 0, transients must be a pointer to an array of transientCount valid XrHapticParametricTransientEXT structures
streamFrameType must be a valid XrHapticParametricStreamFrameTypeEXT value
The amplitudePointCount parameter must be greater than 0

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

This work is licensed under a Creative Commons Attribution 4.0 International License.

XrHapticParametricVibrationEXT(3) Manual Page

Name

C Specification

Members

Description

See Also

Document Notes

Copyright