Merge pull request #90645 from Malcolmnixon/unified-xr-trackers

Rework XR Trackers to have a common ancestor
godotengine · Apr 22, 2024 · bffaa98 · bffaa98
2 parents e500046 + 823ae7b
commit bffaa98
Show file tree

Hide file tree

Showing 49 changed files with 768 additions and 635 deletions.
diff --git a/doc/classes/XRBodyModifier3D.xml b/doc/classes/XRBodyModifier3D.xml
@@ -4,15 +4,15 @@
 		A node for driving body meshes from [XRBodyTracker] data.
 	</brief_description>
 	<description>
-		This node uses body tracking data from a [XRBodyTracker] to animate the skeleton of a body mesh.
-		This node positions itself at the [constant XRBodyTracker.JOINT_ROOT] position and scales itself to [member XRServer.world_scale]. Adding the body model as a child of this node will result in the model being positioned and scaled correctly for XR experiences.
+		This node uses body tracking data from an [XRBodyTracker] to pose the skeleton of a body mesh.
+		Positioning of the body is performed by creating an [XRNode3D] ancestor of the body mesh driven by the same [XRBodyTracker].
 		The body tracking position-data is scaled by [member Skeleton3D.motion_scale] when applied to the skeleton, which can be used to adjust the tracked body to match the scale of the body model.
 	</description>
 	<tutorials>
 		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
 	</tutorials>
 	<members>
-		<member name="body_tracker" type="StringName" setter="set_body_tracker" getter="get_body_tracker" default="&amp;&quot;/user/body&quot;">
+		<member name="body_tracker" type="StringName" setter="set_body_tracker" getter="get_body_tracker" default="&amp;&quot;/user/body_tracker&quot;">
 			The name of the [XRBodyTracker] registered with [XRServer] to obtain the body tracking data from.
 		</member>
 		<member name="body_update" type="int" setter="set_body_update" getter="get_body_update" enum="XRBodyModifier3D.BodyUpdate" is_bitfield="true" default="7">
@@ -21,9 +21,6 @@
 		<member name="bone_update" type="int" setter="set_bone_update" getter="get_bone_update" enum="XRBodyModifier3D.BoneUpdate" default="0">
 			Specifies the type of updates to perform on the bones.
 		</member>
-		<member name="show_when_tracked" type="bool" setter="set_show_when_tracked" getter="get_show_when_tracked" default="true">
-			If true then the nodes visibility is determined by whether tracking data is available.
-		</member>
 	</members>
 	<constants>
 		<constant name="BODY_UPDATE_UPPER_BODY" value="1" enum="BodyUpdate" is_bitfield="true">

diff --git a/doc/classes/XRBodyTracker.xml b/doc/classes/XRBodyTracker.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="XRBodyTracker" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="XRBodyTracker" inherits="XRPositionalTracker" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
 		A tracked body in XR.
 	</brief_description>
@@ -49,6 +49,7 @@
 		<member name="has_tracking_data" type="bool" setter="set_has_tracking_data" getter="get_has_tracking_data" default="false">
 			If [code]true[/code], the body tracking data is valid.
 		</member>
+		<member name="type" type="int" setter="set_tracker_type" getter="get_tracker_type" overrides="XRTracker" enum="XRServer.TrackerType" default="32" />
 	</members>
 	<constants>
 		<constant name="BODY_FLAG_UPPER_BODY_SUPPORTED" value="1" enum="BodyFlags" is_bitfield="true">

diff --git a/doc/classes/XRControllerTracker.xml b/doc/classes/XRControllerTracker.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="XRControllerTracker" inherits="XRPositionalTracker" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A tracked controller.
+	</brief_description>
+	<description>
+		An instance of this object represents a controller that is tracked.
+		As controllers are turned on and the [XRInterface] detects them, instances of this object are automatically added to this list of active tracking objects accessible through the [XRServer].
+		The [XRController3D] consumes objects of this type and should be used in your project.
+	</description>
+	<tutorials>
+		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
+	</tutorials>
+	<members>
+		<member name="type" type="int" setter="set_tracker_type" getter="get_tracker_type" overrides="XRTracker" enum="XRServer.TrackerType" default="2" />
+	</members>
+</class>
diff --git a/doc/classes/XRFaceModifier3D.xml b/doc/classes/XRFaceModifier3D.xml
@@ -12,7 +12,7 @@
 		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
 	</tutorials>
 	<members>
-		<member name="face_tracker" type="StringName" setter="set_face_tracker" getter="get_face_tracker" default="&amp;&quot;/user/head&quot;">
+		<member name="face_tracker" type="StringName" setter="set_face_tracker" getter="get_face_tracker" default="&amp;&quot;/user/face_tracker&quot;">
 			The [XRFaceTracker] path.
 		</member>
 		<member name="target" type="NodePath" setter="set_target" getter="get_target" default="NodePath(&quot;&quot;)">

diff --git a/doc/classes/XRFaceTracker.xml b/doc/classes/XRFaceTracker.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="XRFaceTracker" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="XRFaceTracker" inherits="XRTracker" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
 		A tracked face.
 	</brief_description>
@@ -31,6 +31,7 @@
 		<member name="blend_shapes" type="PackedFloat32Array" setter="set_blend_shapes" getter="get_blend_shapes" default="PackedFloat32Array()">
 			The array of face blend shape weights with indices corresponding to the [enum BlendShapeEntry] enum.
 		</member>
+		<member name="type" type="int" setter="set_tracker_type" getter="get_tracker_type" overrides="XRTracker" enum="XRServer.TrackerType" default="64" />
 	</members>
 	<constants>
 		<constant name="FT_EYE_LOOK_OUT_RIGHT" value="0" enum="BlendShapeEntry">

diff --git a/doc/classes/XRHandModifier3D.xml b/doc/classes/XRHandModifier3D.xml
@@ -4,8 +4,8 @@
 		A node for driving hand meshes from [XRHandTracker] data.
 	</brief_description>
 	<description>
-		This node uses hand tracking data from a [XRHandTracker] to animate the skeleton of a hand mesh.
-		This node positions itself at the [constant XRHandTracker.HAND_JOINT_PALM] position and scales itself to [member XRServer.world_scale]. Adding the hand model as a child of this node will result in the model being positioned and scaled correctly for XR experiences.
+		This node uses hand tracking data from an [XRHandTracker] to pose the skeleton of a hand mesh.
+		Positioning of hands is performed by creating an [XRNode3D] ancestor of the hand mesh driven by the same [XRHandTracker].
 		The hand tracking position-data is scaled by [member Skeleton3D.motion_scale] when applied to the skeleton, which can be used to adjust the tracked hand to match the scale of the hand model.
 	</description>
 	<tutorials>
@@ -15,7 +15,7 @@
 		<member name="bone_update" type="int" setter="set_bone_update" getter="get_bone_update" enum="XRHandModifier3D.BoneUpdate" default="0">
 			Specifies the type of updates to perform on the bones.
 		</member>
-		<member name="hand_tracker" type="StringName" setter="set_hand_tracker" getter="get_hand_tracker" default="&amp;&quot;/user/left&quot;">
+		<member name="hand_tracker" type="StringName" setter="set_hand_tracker" getter="get_hand_tracker" default="&amp;&quot;/user/hand_tracker/left&quot;">
 			The name of the [XRHandTracker] registered with [XRServer] to obtain the hand tracking data from.
 		</member>
 	</members>

diff --git a/doc/classes/XRHandTracker.xml b/doc/classes/XRHandTracker.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="XRHandTracker" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="XRHandTracker" inherits="XRPositionalTracker" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
 		A tracked hand in XR.
 	</brief_description>
@@ -11,6 +11,12 @@
 		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
 	</tutorials>
 	<methods>
+		<method name="get_hand" qualifiers="const">
+			<return type="int" enum="XRHandTracker.Hand" />
+			<description>
+				Returns the type of hand.
+			</description>
+		</method>
 		<method name="get_hand_joint_angular_velocity" qualifiers="const">
 			<return type="Vector3" />
 			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
@@ -46,6 +52,13 @@
 				Returns the transform for the given hand joint.
 			</description>
 		</method>
+		<method name="set_hand">
+			<return type="void" />
+			<param index="0" name="hand" type="int" enum="XRHandTracker.Hand" />
+			<description>
+				Sets the type of hand.
+			</description>
+		</method>
 		<method name="set_hand_joint_angular_velocity">
 			<return type="void" />
 			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
@@ -88,15 +101,13 @@
 		</method>
 	</methods>
 	<members>
-		<member name="hand" type="int" setter="set_hand" getter="get_hand" enum="XRHandTracker.Hand" default="0">
-			The type of hand.
-		</member>
 		<member name="hand_tracking_source" type="int" setter="set_hand_tracking_source" getter="get_hand_tracking_source" enum="XRHandTracker.HandTrackingSource" default="0">
 			The source of the hand tracking data.
 		</member>
 		<member name="has_tracking_data" type="bool" setter="set_has_tracking_data" getter="get_has_tracking_data" default="false">
 			If [code]true[/code], the hand tracking data is valid.
 		</member>
+		<member name="type" type="int" setter="set_tracker_type" getter="get_tracker_type" overrides="XRTracker" enum="XRServer.TrackerType" default="16" />
 	</members>
 	<constants>
 		<constant name="HAND_LEFT" value="0" enum="Hand">

diff --git a/doc/classes/XRNode3D.xml b/doc/classes/XRNode3D.xml
@@ -46,6 +46,9 @@
 			The name of the pose we're bound to. Which poses a tracker supports is not known during design time.
 			Godot defines number of standard pose names such as [code]aim[/code] and [code]grip[/code] but other may be configured within a given [XRInterface].
 		</member>
+		<member name="show_when_tracked" type="bool" setter="set_show_when_tracked" getter="get_show_when_tracked" default="false">
+			Enables showing the node when tracking starts, and hiding the node when tracking is lost.
+		</member>
 		<member name="tracker" type="StringName" setter="set_tracker" getter="get_tracker" default="&amp;&quot;&quot;">
 			The name of the tracker we're bound to. Which trackers are available is not known during design time.
 			Godot defines a number of standard trackers such as [code]left_hand[/code] and [code]right_hand[/code] but others may be configured within a given [XRInterface].

diff --git a/doc/classes/XRPositionalTracker.xml b/doc/classes/XRPositionalTracker.xml
@@ -1,18 +1,18 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="XRPositionalTracker" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="XRPositionalTracker" inherits="XRTracker" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
 		A tracked object.
 	</brief_description>
 	<description>
 		An instance of this object represents a device that is tracked, such as a controller or anchor point. HMDs aren't represented here as they are handled internally.
 		As controllers are turned on and the [XRInterface] detects them, instances of this object are automatically added to this list of active tracking objects accessible through the [XRServer].
-		The [XRController3D] and [XRAnchor3D] both consume objects of this type and should be used in your project. The positional trackers are just under-the-hood objects that make this all work. These are mostly exposed so that GDExtension-based interfaces can interact with them.
+		The [XRNode3D] and [XRAnchor3D] both consume objects of this type and should be used in your project. The positional trackers are just under-the-hood objects that make this all work. These are mostly exposed so that GDExtension-based interfaces can interact with them.
 	</description>
 	<tutorials>
 		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
 	</tutorials>
 	<methods>
-		<method name="get_input" qualifiers="const">
+		<method name="get_input" qualifiers="const" deprecated="Use through [XRControllerTracker].">
 			<return type="Variant" />
 			<param index="0" name="name" type="StringName" />
 			<description>
@@ -40,7 +40,7 @@
 				Marks this pose as invalid, we don't clear the last reported state but it allows users to decide if trackers need to be hidden if we lose tracking or just remain at their last known position.
 			</description>
 		</method>
-		<method name="set_input">
+		<method name="set_input" deprecated="Use through [XRControllerTracker].">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" />
 			<param index="1" name="value" type="Variant" />
@@ -61,23 +61,12 @@
 		</method>
 	</methods>
 	<members>
-		<member name="description" type="String" setter="set_tracker_desc" getter="get_tracker_desc" default="&quot;&quot;">
-			The description of this tracker.
-		</member>
 		<member name="hand" type="int" setter="set_tracker_hand" getter="get_tracker_hand" enum="XRPositionalTracker.TrackerHand" default="0">
 			Defines which hand this tracker relates to.
 		</member>
-		<member name="name" type="StringName" setter="set_tracker_name" getter="get_tracker_name" default="&amp;&quot;Unknown&quot;">
-			The unique name of this tracker. The trackers that are available differ between various XR runtimes and can often be configured by the user. Godot maintains a number of reserved names that it expects the [XRInterface] to implement if applicable:
-			- [code]left_hand[/code] identifies the controller held in the players left hand
-			- [code]right_hand[/code] identifies the controller held in the players right hand
-		</member>
 		<member name="profile" type="String" setter="set_tracker_profile" getter="get_tracker_profile" default="&quot;&quot;">
 			The profile associated with this tracker, interface dependent but will indicate the type of controller being tracked.
 		</member>
-		<member name="type" type="int" setter="set_tracker_type" getter="get_tracker_type" enum="XRServer.TrackerType" default="128">
-			The type of tracker.
-		</member>
 	</members>
 	<signals>
 		<signal name="button_pressed">
@@ -135,5 +124,8 @@
 		<constant name="TRACKER_HAND_RIGHT" value="2" enum="TrackerHand">
 			This tracker is the right hand controller.
 		</constant>
+		<constant name="TRACKER_HAND_MAX" value="3" enum="TrackerHand">
+			Represents the size of the [enum TrackerHand] enum.
+		</constant>
 	</constants>
 </class>