C Specification

XrHandJointLocationsEXT structure returns the state of the hand joint locations.

// Provided by XR_EXT_hand_tracking
typedef struct XrHandJointLocationsEXT {
    XrStructureType            type;
    void*                      next;
    XrBool32                   isActive;
    uint32_t                   jointCount;
    XrHandJointLocationEXT*    jointLocations;
} XrHandJointLocationsEXT;

Members

Member Descriptions

  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain, such as XrHandJointVelocitiesEXT.

  • isActive is an XrBool32 indicating if the hand tracker is actively tracking.

  • jointCount is a uint32_t describing the count of elements in jointLocations array.

  • jointLocations is an array of XrHandJointLocationEXT receiving the returned hand joint locations.

Description

The application must allocate the memory for the output array jointLocations that can contain at least jointCount of XrHandJointLocationEXT.

The application must set jointCount as described by the XrHandJointSetEXT when creating the XrHandTrackerEXT otherwise the runtime must return XR_ERROR_VALIDATION_FAILURE.

The runtime must return jointLocations representing the range of motion of a human hand, without any obstructions. Input systems that obstruct the movement of the user’s hand (e.g.: a held controller preventing the user from making a fist) or that have only limited ability to track finger positions must use the information available to them to emulate an unobstructed range of motion.

The runtime must update the jointLocations array ordered so that the application can index elements using the corresponding hand joint enum (e.g. XrHandJointEXT) as described by XrHandJointSetEXT when creating the XrHandTrackerEXT. For example, when the XrHandTrackerEXT is created with XR_HAND_JOINT_SET_DEFAULT_EXT, the application must set the jointCount to XR_HAND_JOINT_COUNT_EXT, and the runtime must fill the jointLocations array ordered so that it may be indexed by the XrHandJointEXT enum.

If the returned isActive is true, the runtime must return all joint locations with both XR_SPACE_LOCATION_POSITION_VALID_BIT and XR_SPACE_LOCATION_ORIENTATION_VALID_BIT set. Although, in this case, some joint space locations may be untracked (i.e. XR_SPACE_LOCATION_POSITION_TRACKED_BIT or XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT is unset).

If the returned isActive is false, it indicates the hand tracker did not detect the hand input or the application lost input focus. In this case, the runtime must return all jointLocations with neither XR_SPACE_LOCATION_POSITION_VALID_BIT nor XR_SPACE_LOCATION_ORIENTATION_VALID_BIT set.

Valid Usage (Implicit)

See Also

XR_EXT_hand_tracking, XrBool32, XrHandJointLocationEXT, XrStructureType, xrLocateHandJointsEXT

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.