Merge pull request #109753 from dsnopek/openxr-ext-threading-docs

`OpenXRExtensionWrapper`: Document how to safely work when rendering with "Separate" thread model

Author: Repiteo

modules/openxr/doc_classes/OpenXRAPIExtension.xml

@@ -228,20 +228,23 @@
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Registers the given extension as a composition layer provider.
+				[b]Note:[/b] This cannot be called after the OpenXR session has started. However, it can be called in [method OpenXRExtensionWrapper._on_session_created].
 			</description>
 		</method>
 		<method name="register_frame_info_extension">
 			<return type="void" />
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Registers the given extension as modifying frame info via the [method OpenXRExtensionWrapper._set_frame_wait_info_and_get_next_pointer], [method OpenXRExtensionWrapper._set_view_locate_info_and_get_next_pointer], or [method OpenXRExtensionWrapper._set_frame_end_info_and_get_next_pointer] virtual methods.
+				[b]Note:[/b] This cannot be called after the OpenXR session has started. However, it can be called in [method OpenXRExtensionWrapper._on_session_created].
 			</description>
 		</method>
 		<method name="register_projection_views_extension">
 			<return type="void" />
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Registers the given extension as a provider of additional data structures to projections views.
+				[b]Note:[/b] This cannot be called after the OpenXR session has started. However, it can be called in [method OpenXRExtensionWrapper._on_session_created].
 			</description>
 		</method>
 		<method name="set_custom_play_space">
@@ -307,20 +310,23 @@
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Unregisters the given extension as a composition layer provider.
+				[b]Note:[/b] This cannot be called while the OpenXR session is still running.
 			</description>
 		</method>
 		<method name="unregister_frame_info_extension">
 			<return type="void" />
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Unregisters the given extension as modifying frame info.
+				[b]Note:[/b] This cannot be called while the OpenXR session is still running.
 			</description>
 		</method>
 		<method name="unregister_projection_views_extension">
 			<return type="void" />
 			<param index="0" name="extension" type="OpenXRExtensionWrapper" />
 			<description>
 				Unregisters the given extension as a provider of additional data structures to projections views.
+				[b]Note:[/b] This cannot be called while the OpenXR session is still running.
 			</description>
 		</method>
 		<method name="xr_result">

modules/openxr/doc_classes/OpenXRExtensionWrapper.xml

@@ -5,6 +5,11 @@
 	</brief_description>
 	<description>
 		[OpenXRExtensionWrapper] allows implementing OpenXR extensions with GDExtension. The extension should be registered with [method register_extension_wrapper].
+		When [OpenXRInterface] is initialized as the primary interface and any [Viewport] has [member Viewport.use_xr] set to [code]true[/code], OpenXR will become involved in Godot's rendering process. If [member ProjectSettings.rendering/driver/threads/thread_model] is set to "Separate", Godot's renderer will run on its own thread, and special care must be taken in all [OpenXRExtensionWrapper]s in order to prevent crashes or unexpected behavior. Some virtual methods will be called on the render thread, and any data they access should not be directly written to on the main thread. This is to prevent two potential issues:
+		1. Changes intended for the next frame, taking effect on the current frame. When using the "Separate" thread model, the main thread will immediately start working on the next frame while the render thread may still be rendering the current frame. If the main thread changes anything used by the render thread directly, the change could end up being used one frame earlier than intended.
+		2. Reading and writing to the same data at the same time from different threads can lead to the render thread using data in an invalid state.
+		In most cases, the solution is to use [method RenderingServer.call_on_render_thread] to schedule [Callable]s to write to any data used on the render thread. When using the "Separate" thread model, these [Callable]s will run after the renderer finishes the current frame and before it starts rendering the next frame. When not using this mode, they'll run immediately, so it's recommended to always use [method RenderingServer.call_on_render_thread] in these cases, which will allow your code to do the right thing regardless of the thread model.
+		Any virtual methods that run on the render thread will be noted below.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -15,13 +20,15 @@
 			<description>
 				Returns a pointer to an [code]XrCompositionLayerBaseHeader[/code] struct to provide the given composition layer.
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_composition_layer_provider].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_get_composition_layer_count" qualifiers="virtual">
 			<return type="int" />
 			<description>
 				Returns the number of composition layers this extension wrapper provides via [method _get_composition_layer].
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_composition_layer_provider].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_get_composition_layer_order" qualifiers="virtual">
@@ -30,6 +37,7 @@
 			<description>
 				Returns an integer that will be used to sort the given composition layer provided via [method _get_composition_layer]. Lower numbers will move the layer to the front of the list, and higher numbers to the end. The default projection layer has an order of [code]0[/code], so layers provided by this method should probably be above or below (but not exactly) [code]0[/code].
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_composition_layer_provider].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_get_requested_extensions" qualifiers="virtual">
@@ -50,6 +58,7 @@
 			<return type="Dictionary[]" />
 			<description>
 				Gets an array of [Dictionary]s that represent properties, just like [method Object._get_property_list], that will be added to [OpenXRCompositionLayer] nodes.
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_get_viewport_composition_layer_extension_property_defaults" qualifiers="virtual">
@@ -62,6 +71,7 @@
 			<return type="void" />
 			<description>
 				Called before the OpenXR instance is created.
+				[b]Note:[/b] This virtual method will be called on the main thread, however, it will be called [i]before[/i] OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
 			</description>
 		</method>
 		<method name="_on_event_polled" qualifiers="virtual">
@@ -76,18 +86,21 @@
 			<param index="0" name="instance" type="int" />
 			<description>
 				Called right after the OpenXR instance is created.
+				[b]Note:[/b] This virtual method will be called on the main thread, however, it will be called [i]before[/i] OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
 			</description>
 		</method>
 		<method name="_on_instance_destroyed" qualifiers="virtual">
 			<return type="void" />
 			<description>
 				Called right before the OpenXR instance is destroyed.
+				[b]Note:[/b] This virtual method will be called on the main thread, however, it will be called [i]after[/i] OpenXR is done being involved in rendering, so it is safe to write to data that was used by the render thread.
 			</description>
 		</method>
 		<method name="_on_main_swapchains_created" qualifiers="virtual">
 			<return type="void" />
 			<description>
 				Called right after the main swapchains are (re)created.
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_on_post_draw_viewport" qualifiers="virtual">
@@ -96,19 +109,22 @@
 			<description>
 				Called right after the given viewport is rendered.
 				[b]Note:[/b] The draw commands might only be queued at this point, not executed.
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_on_pre_draw_viewport" qualifiers="virtual">
 			<return type="void" />
 			<param index="0" name="viewport" type="RID" />
 			<description>
 				Called right before the given viewport is rendered.
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_on_pre_render" qualifiers="virtual">
 			<return type="void" />
 			<description>
 				Called right before the XR viewports begin their rendering step.
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_on_process" qualifiers="virtual">
@@ -129,12 +145,14 @@
 			<param index="0" name="session" type="int" />
 			<description>
 				Called right after the OpenXR session is created.
+				[b]Note:[/b] This virtual method will be called on the main thread, however, it will be called [i]before[/i] OpenXR becomes involved in rendering, so it is safe to write to data that will be used by the render thread.
 			</description>
 		</method>
 		<method name="_on_session_destroyed" qualifiers="virtual">
 			<return type="void" />
 			<description>
 				Called right before the OpenXR session is destroyed.
+				[b]Note:[/b] This virtual method will be called on the main thread, however, it will be called [i]after[/i] OpenXR is done being involved in rendering, so it is safe to write to data that was used by the render thread.
 			</description>
 		</method>
 		<method name="_on_state_exiting" qualifiers="virtual">
@@ -206,6 +224,7 @@
 			<description>
 				Adds additional data structures to Android surface swapchains created by [OpenXRCompositionLayer].
 				[param property_values] contains the values of the properties returned by [method _get_viewport_composition_layer_extension_properties].
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_set_frame_end_info_and_get_next_pointer" qualifiers="virtual">
@@ -214,6 +233,7 @@
 			<description>
 				Adds additional data structures to [code]XrFrameEndInfo[/code].
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_frame_info_extension].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_set_frame_wait_info_and_get_next_pointer" qualifiers="virtual">
@@ -222,6 +242,7 @@
 			<description>
 				Adds additional data structures to [code]XrFrameWaitInfo[/code].
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_frame_info_extension].
+				[b]Note:[/b] This virtual method will be called on the render thread.
 			</description>
 		</method>
 		<method name="_set_hand_joint_locations_and_get_next_pointer" qualifiers="virtual">
@@ -245,6 +266,7 @@
 			<param index="1" name="next_pointer" type="void*" />
 			<description>
 				Adds additional data structures to the projection view of the given [param view_index].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_set_reference_space_create_info_and_get_next_pointer" qualifiers="virtual">
@@ -282,6 +304,7 @@
 			<description>
 				Adds additional data structures to [code]XrViewLocateInfo[/code].
 				This will only be called if the extension previously registered itself with [method OpenXRAPIExtension.register_frame_info_extension].
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="_set_viewport_composition_layer_and_get_next_pointer" qualifiers="virtual">
@@ -293,6 +316,7 @@
 				Adds additional data structures to composition layers created by [OpenXRCompositionLayer].
 				[param property_values] contains the values of the properties returned by [method _get_viewport_composition_layer_extension_properties].
 				[param layer] is a pointer to an [code]XrCompositionLayerBaseHeader[/code] struct.
+				[b]Note:[/b] This virtual method will be called on the render thread. Additionally, the data it returns will be used shortly after this method is called, so it needs to remain valid until the next time [method _on_pre_render] runs.
 			</description>
 		</method>
 		<method name="get_openxr_api">
@@ -305,6 +329,7 @@
 			<return type="void" />
 			<description>
 				Registers the extension. This should happen at core module initialization level.
+				[b]Note:[/b] This cannot be called once OpenXR has been initialized.
 			</description>
 		</method>
 	</methods>