C Specification

The XrInteractionProfileDpadBindingEXT structure is defined as:

// Provided by XR_EXT_dpad_binding
typedef struct XrInteractionProfileDpadBindingEXT {
    XrStructureType              type;
    const void*                  next;
    XrPath                       binding;
    XrActionSet                  actionSet;
    float                        forceThreshold;
    float                        forceThresholdReleased;
    float                        centerRegion;
    float                        wedgeAngle;
    XrBool32                     isSticky;
    const XrHapticBaseHeader*    onHaptic;
    const XrHapticBaseHeader*    offHaptic;
} XrInteractionProfileDpadBindingEXT;

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.

  • binding is the input path used for the specified actions in the suggested binding list to be used as a dpad. E.g. path:/user/hand/right/input/thumbstick

  • actionSet is the action set for which this dpad will be active. The implementation must use the parameters from this structure for any actions from this action set that are bound to one of the dpad subpaths for this input path.

  • forceThreshold a number in the half-open range (0, 1] representing the force value threshold at or above which (≥) a dpad input will transition from inactive to active.

  • forceThresholdReleased a number in the half-open range (0, 1] representing the force value threshold strictly below which (<) a dpad input will transition from active to inactive.

  • centerRegion defines the center region of the thumbstick or trackpad. This is the radius, in the input value space, of a logically circular region in the center of the input, in the range (0, 1).

  • wedgeAngle indicates the angle in radians of each direction region and is a value in the half-open range [0, π).

  • isSticky indicates that the implementation will latch the first region that is activated and continue to indicate that the binding for that region is true until the user releases the input underlying the virtual dpad.

  • onHaptic is the haptic output that the runtime must trigger when the binding changes from false to true. If this field is NULL, the runtime must not trigger any haptic output on the threshold. This field can point to any supported sub-type of XrHapticBaseHeader.

  • offHaptic is the haptic output that the runtime must trigger when the binding changes from true to false. If this field is NULL, the runtime must not trigger any haptic output on the threshold. This field can point to any supported sub-type of XrHapticBaseHeader.

Description

The XrInteractionProfileDpadBindingEXT structure is an input struct that defines how to use any two-axis input to provide dpad-like functionality to the application. The struct must be added for each input that should be treated as a dpad to the XrBindingModificationsKHR::bindingModifications array in the XrBindingModificationsKHR structure (See XR_KHR_binding_modification extension).

Runtimes are free to ignore any of the fields when not obeying the bindings, but may use it for automatic rebindings of actions.

The implementation must return XR_ERROR_VALIDATION_FAILURE from xrSuggestInteractionProfileBindings if any of the following are true:

  • forceThreshold or forceThresholdReleased are outside the half-open range (0, 1]

  • forceThreshold < forceThresholdReleased

  • centerRegion is outside the exclusive range (0, 1)

  • wedgeAngle outside the half-open range [0, π)

If more than one XrInteractionProfileDpadBindingEXT is provided for the same input identifier, including top level path (e.g. /user/hand/left/input/thumbstick), and two or more of them specify the same actionset, the runtime must return XR_ERROR_VALIDATION_FAILURE. If the same input identifier, including top level path, is used for more than one action set, in addition to inputs being suppressed by higher priority action sets, haptic events from dpads are also suppressed.

For example, a Valve Index controller binding with a "Walking" action set can have a dpad on each of:

  • left thumbstick

  • right thumbstick

  • left trackpad

  • right trackpad

Another action set can also have a dpad active on each of those inputs, and they can have different settings. If both action sets are active, the higher priority one trumps the lower priority one, and the lower priority one is suppressed.

Valid Usage (Implicit)

See Also

XR_EXT_dpad_binding, XrActionSet, XrBindingModificationBaseHeaderKHR, XrBool32, XrHapticBaseHeader, XrPath, XrStructureType, xrSuggestInteractionProfileBindings

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

Copyright 2014-2024, The Khronos Group Inc.

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