OpenXR: Add support for render models extension

doc/classes/ProjectSettings.xml

@@ -3451,6 +3451,10 @@
 			If [code]true[/code], support for the unobstructed data source is requested. If supported, you will receive hand tracking data based on the actual finger positions of the user often determined by optical tracking.
 			[b]Note:[/b] This requires the OpenXR data source extension and unobstructed handtracking to be supported by the XR runtime. If not supported this setting will be ignored. [member xr/openxr/extensions/hand_tracking] must be enabled for this setting to be used.
 		</member>
+		<member name="xr/openxr/extensions/render_model" type="bool" setter="" getter="" default="false">
+			If [code]true[/code] we enable the render model extension if available.
+			[b]Note:[/b] This relates to the core OpenXR render model extension and has no relation to any vendor render model extensions.
+		</member>
 		<member name="xr/openxr/form_factor" type="int" setter="" getter="" default="&quot;0&quot;">
 			Specify whether OpenXR should be configured for an HMD or a hand held device.
 		</member>

main/main.cpp

@@ -2771,6 +2771,7 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 	GLOBAL_DEF_BASIC("xr/openxr/extensions/hand_tracking_controller_data_source", false); // XR_HAND_TRACKING_DATA_SOURCE_CONTROLLER_EXT
 	GLOBAL_DEF_RST_BASIC("xr/openxr/extensions/hand_interaction_profile", false);
 	GLOBAL_DEF_RST_BASIC("xr/openxr/extensions/eye_gaze_interaction", false);
+	GLOBAL_DEF_BASIC("xr/openxr/extensions/render_model", false);
 
 	// OpenXR Binding modifier settings
 	GLOBAL_DEF_BASIC("xr/openxr/binding_modifiers/analog_threshold", false);

modules/openxr/config.py

@@ -40,6 +40,9 @@ def get_doc_classes():
         "OpenXRBindingModifierEditor",
         "OpenXRHapticBase",
         "OpenXRHapticVibration",
+        "OpenXRRenderModelExtension",
+        "OpenXRRenderModel",
+        "OpenXRRenderModelManager",
     ]
 
 

modules/openxr/doc_classes/OpenXRExtensionWrapper.xml

@@ -185,6 +185,12 @@
 				Called when the OpenXR session state is changed to visible. This means OpenXR is now ready to receive frames.
 			</description>
 		</method>
+		<method name="_on_sync_actions" qualifiers="virtual">
+			<return type="void" />
+			<description>
+				Called when OpenXR has performed its action sync.
+			</description>
+		</method>
 		<method name="_on_viewport_composition_layer_destroyed" qualifiers="virtual">
 			<return type="void" />
 			<param index="0" name="layer" type="const void*" />

modules/openxr/doc_classes/OpenXRRenderModel.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OpenXRRenderModel" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
+	<brief_description>
+		This node will display an OpenXR render model.
+	</brief_description>
+	<description>
+		This node will display an OpenXR render model by accessing the associated GLTF and processes all animation data (if supported by the XR runtime).
+		Render models were introduced to allow showing the correct model for the controller (or other device) the user has in hand, since the OpenXR action map does not provide information about the hardware used by the user. Note that while the controller (or device) can be somewhat inferred by the bound action map profile, this is a dangerous approach as the user may be using hardware not known at time of development and OpenXR will simply simulate an available interaction profile.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_top_level_path" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns the top level path related to this render model.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="render_model" type="RID" setter="set_render_model" getter="get_render_model" default="RID()">
+			The render model RID for the render model to load, as returned by [method OpenXRRenderModelExtension.render_model_create] or [method OpenXRRenderModelExtension.render_model_get_all].
+		</member>
+	</members>
+	<signals>
+		<signal name="render_model_top_level_path_changed">
+			<description>
+				Emitted when the top level path of this render model has changed.
+			</description>
+		</signal>
+	</signals>
+</class>

modules/openxr/doc_classes/OpenXRRenderModelExtension.xml

@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OpenXRRenderModelExtension" inherits="OpenXRExtensionWrapper" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
+	<brief_description>
+		This class implements the OpenXR Render Model Extension.
+	</brief_description>
+	<description>
+		This class implements the OpenXR Render Model Extension, if enabled it will maintain a list of active render models and provides an interface to the render model data.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="is_active" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if OpenXR's render model extension is supported and enabled.
+				[b]Note:[/b] This only returns a valid value after OpenXR has been initialized.
+			</description>
+		</method>
+		<method name="render_model_create">
+			<return type="RID" />
+			<param index="0" name="render_model_id" type="int" />
+			<description>
+				Creates a render model object within OpenXR using a render model id.
+				[b]Note:[/b] This function is exposed for dependent OpenXR extensions that provide render model ids to be used with the render model extension.
+			</description>
+		</method>
+		<method name="render_model_destroy">
+			<return type="void" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Destroys a render model object within OpenXR that was previously created with [method render_model_create].
+				[b]Note:[/b] This function is exposed for dependent OpenXR extensions that provide render model ids to be used with the render model extension.
+			</description>
+		</method>
+		<method name="render_model_get_all">
+			<return type="RID[]" />
+			<description>
+				Returns an array of all currently active render models registered with this extension.
+			</description>
+		</method>
+		<method name="render_model_get_animatable_node_count" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns the number of animatable nodes this render model has.
+			</description>
+		</method>
+		<method name="render_model_get_animatable_node_name" qualifiers="const">
+			<return type="String" />
+			<param index="0" name="render_model" type="RID" />
+			<param index="1" name="index" type="int" />
+			<description>
+				Returns the name of the given animatable node.
+			</description>
+		</method>
+		<method name="render_model_get_animatable_node_transform" qualifiers="const">
+			<return type="Transform3D" />
+			<param index="0" name="render_model" type="RID" />
+			<param index="1" name="index" type="int" />
+			<description>
+				Returns the current local transform for an animatable node. This is updated every frame.
+			</description>
+		</method>
+		<method name="render_model_get_confidence" qualifiers="const">
+			<return type="int" enum="XRPose.TrackingConfidence" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns the tracking confidence of the tracking data for the render model.
+			</description>
+		</method>
+		<method name="render_model_get_root_transform" qualifiers="const">
+			<return type="Transform3D" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns the root transform of a render model. This is the tracked position relative to our [XROrigin3D] node.
+			</description>
+		</method>
+		<method name="render_model_get_subaction_paths">
+			<return type="PackedStringArray" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns a list of active subaction paths for this [param render_model].
+				[b]Note:[/b] If different devices are bound to your actions than available in suggested interaction bindings, this information shows paths related to the interaction bindings being mimicked by that device.
+			</description>
+		</method>
+		<method name="render_model_get_top_level_path" qualifiers="const">
+			<return type="String" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns the top level path associated with this [param render_model]. If provided this identifies whether the render model is associated with the players hands or other body part.
+			</description>
+		</method>
+		<method name="render_model_is_animatable_node_visible" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="render_model" type="RID" />
+			<param index="1" name="index" type="int" />
+			<description>
+				Returns [code]true[/code] if this animatable node should be visible.
+			</description>
+		</method>
+		<method name="render_model_new_scene_instance" qualifiers="const">
+			<return type="Node3D" />
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Returns an instance of a subscene that contains all [MeshInstance3D] nodes that allow you to visualize the render model.
+			</description>
+		</method>
+	</methods>
+	<signals>
+		<signal name="render_model_added">
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Emitted when a new render model is added.
+			</description>
+		</signal>
+		<signal name="render_model_removed">
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Emitted when a render model is removed.
+			</description>
+		</signal>
+		<signal name="render_model_top_level_path_changed">
+			<param index="0" name="render_model" type="RID" />
+			<description>
+				Emitted when the top level path associated with a render model changed.
+			</description>
+		</signal>
+	</signals>
+</class>

modules/openxr/doc_classes/OpenXRRenderModelManager.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OpenXRRenderModelManager" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
+	<brief_description>
+		Helper node that will automatically manage displaying render models.
+	</brief_description>
+	<description>
+		This helper node will automatically manage displaying render models. It will create new [OpenXRRenderModel] nodes as controllers and other hand held devices are detected, and remove those nodes when they are deactivated.
+		[b]Note:[/b] If you want more control over this logic you can alternatively call [method OpenXRRenderModelExtension.render_model_get_all] to obtain a list of active render model ids and create [OpenXRRenderModel] instances for each render model id provided.
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="make_local_to_pose" type="String" setter="set_make_local_to_pose" getter="get_make_local_to_pose" default="&quot;&quot;">
+			Position render models local to this pose (this will adjust the position of the render models container node).
+		</member>
+		<member name="tracker" type="int" setter="set_tracker" getter="get_tracker" enum="OpenXRRenderModelManager.RenderModelTracker" default="0">
+			Limits render models to the specified tracker. Include: 0 = All render models, 1 = Render models not related to a tracker, 2 = Render models related to the left hand tracker, 3 = Render models related to the right hand tracker.
+		</member>
+	</members>
+	<signals>
+		<signal name="render_model_added">
+			<param index="0" name="render_model" type="OpenXRRenderModel" />
+			<description>
+				Emitted when a render model node is added as a child to this node.
+			</description>
+		</signal>
+		<signal name="render_model_removed">
+			<param index="0" name="render_model" type="OpenXRRenderModel" />
+			<description>
+				Emitted when a render model child node is about to be removed from this node.
+			</description>
+		</signal>
+	</signals>
+	<constants>
+		<constant name="RENDER_MODEL_TRACKER_ANY" value="0" enum="RenderModelTracker">
+			All active render models are shown regardless of what tracker they relate to.
+		</constant>
+		<constant name="RENDER_MODEL_TRACKER_NONE_SET" value="1" enum="RenderModelTracker">
+			Only active render models are shown that are not related to any tracker we manage.
+		</constant>
+		<constant name="RENDER_MODEL_TRACKER_LEFT_HAND" value="2" enum="RenderModelTracker">
+			Only active render models are shown that are related to the left hand tracker.
+		</constant>
+		<constant name="RENDER_MODEL_TRACKER_RIGHT_HAND" value="3" enum="RenderModelTracker">
+			Only active render models are shown that are related to the right hand tracker.
+		</constant>
+	</constants>
+</class>

modules/openxr/extensions/openxr_extension_wrapper.cpp

@@ -55,6 +55,7 @@ void OpenXRExtensionWrapper::_bind_methods() {
 	GDVIRTUAL_BIND(_on_instance_destroyed);
 	GDVIRTUAL_BIND(_on_session_created, "session");
 	GDVIRTUAL_BIND(_on_process);
+	GDVIRTUAL_BIND(_on_sync_actions);
 	GDVIRTUAL_BIND(_on_pre_render);
 	GDVIRTUAL_BIND(_on_main_swapchains_created);
 	GDVIRTUAL_BIND(_on_pre_draw_viewport, "viewport");
@@ -252,6 +253,10 @@ void OpenXRExtensionWrapper::on_process() {
 	GDVIRTUAL_CALL(_on_process);
 }
 
+void OpenXRExtensionWrapper::on_sync_actions() {
+	GDVIRTUAL_CALL(_on_sync_actions);
+}
+
 void OpenXRExtensionWrapper::on_pre_render() {
 	GDVIRTUAL_CALL(_on_pre_render);
 }

modules/openxr/extensions/openxr_extension_wrapper.h

@@ -120,6 +120,7 @@ class OpenXRExtensionWrapper : public Object {
 	// this happens right before physics process and normal processing is run.
 	// This is when controller data is queried and made available to game logic.
 	virtual void on_process();
+	virtual void on_sync_actions(); // `on_sync_actions` is called right after we sync our action sets.
 	virtual void on_pre_render(); // `on_pre_render` is called right before we start rendering our XR viewports.
 	virtual void on_main_swapchains_created(); // `on_main_swapchains_created` is called right after our main swapchains are (re)created.
 	virtual void on_pre_draw_viewport(RID p_render_target); // `on_pre_draw_viewport` is called right before we start rendering this viewport
@@ -131,6 +132,7 @@ class OpenXRExtensionWrapper : public Object {
 	GDVIRTUAL0(_on_instance_destroyed);
 	GDVIRTUAL1(_on_session_created, uint64_t);
 	GDVIRTUAL0(_on_process);
+	GDVIRTUAL0(_on_sync_actions);
 	GDVIRTUAL0(_on_pre_render);
 	GDVIRTUAL0(_on_main_swapchains_created);
 	GDVIRTUAL0(_on_session_destroyed);