// Copyright (c) Facebook Technologies, LLC and its affiliates. All rights reserved.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_FB_hand_tracking_capsules.adoc[]

*Contributors*::
    Federico Schliemann, Facebook +
    James Hillery, Facebook +
    Gloria Kennickell, Facebook


*Overview*

The apiext:XR_EXT_hand_tracking extension provides a list of hand joint
poses which include a collision sphere for each joint.
However some physics systems prefer to use capsules as a collision stand in
for the hands.

This extension allows:

* An application to get a list of capsules that represent the volume of the
  hand when using the apiext:XR_EXT_hand_tracking extension.

*New Object Types*

*New Flag Types*

*New Enum Constants*

* ename:XR_HAND_TRACKING_CAPSULE_POINT_COUNT_FB
** ename:XR_FB_HAND_TRACKING_CAPSULE_POINT_COUNT was the original name, and
   is still provided as an alias for backward compatibility.
* ename:XR_HAND_TRACKING_CAPSULE_COUNT_FB
** ename:XR_FB_HAND_TRACKING_CAPSULE_COUNT was the original name, and is
   still provided as an alias for backward compatibility.

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_HAND_TRACKING_CAPSULES_STATE_FB

*New Enums*

*New Structures*


[open,refpage='XrHandCapsuleFB',type='structs',desc='A 3D capsule defined by two points and a radius',xrefs='']
--
The slink:XrHandCapsuleFB structure is defined as:

include::{generated}/api/structs/XrHandCapsuleFB.adoc[]

It describes a collision capsule associated with a hand joint.

.Member Descriptions
****
* pname:points are the two points defining the capsule length.
* pname:radius is the radius of the capsule.
* pname:joint is the hand joint that drives this capsule's transform.
  Multiple capsules may: be attached to the same joint.
****

include::{generated}/validity/structs/XrHandCapsuleFB.adoc[]
--

[open,refpage='XrHandTrackingCapsulesStateFB',type='structs',desc='A list of capsules associated to hand joints',xrefs='']
--

slink:XrHandTrackingCapsulesStateFB can: be provided in the pname:next chain
of slink:XrHandJointLocationsEXT when calling flink:xrLocateHandJointsEXT to
request collision capsule information associated with this hand.

The slink:XrHandTrackingCapsulesStateFB structure is defined as:

include::{generated}/api/structs/XrHandTrackingCapsulesStateFB.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:capsules is an array of capsules.
****

include::{generated}/validity/structs/XrHandTrackingCapsulesStateFB.adoc[]
--

*New Functions*

*Issues*

*Version History*

* Revision 1, 2021-07-07 (Federico Schliemann)
** Initial extension description
* Revision 2, 2021-11-18 (Rylie Pavlik, Collabora, Ltd.)
** Fix typos/naming convention errors: rename
   `XR_FB_HAND_TRACKING_CAPSULE_POINT_COUNT` to
   `XR_HAND_TRACKING_CAPSULE_POINT_COUNT_FB` and
   `XR_FB_HAND_TRACKING_CAPSULE_COUNT` to
   `XR_HAND_TRACKING_CAPSULE_COUNT_FB`, providing the old names as
   compatibility aliases.
* Revision 3, 2022-04-20 (John Kearney)
** Correct next chain parent for `XrHandTrackingCapsulesStateFB` to
   `XrHandJointLocationsEXT`
